Define "Technical Writer" - your thoughts?

[symmetricalMan]

Sorry if this is not the appropriate forum for such a question.... I'm open to suggestions for moving it.

What's a Technical Writer?

I'm asking, because I've been the Senior Technical Writer at my Company for 10+ years, and now I'm being asked to provide HR with a position description. Shouldn't they know?

I suspect I'm really being asked to provide them with a list of my responsibilities as I see them, but it did get me wondering "What is a tech writer?"

I think I know what a tech writer is - at least, I know what it is from my perspective; I write user manuals for the software we develop. Well, that's primarily what I do. That's what I started doing ten years ago. That was the scope of my predecessor's responsibilities.

In reality, I do a bunch of things related to 'documenting techno-babble so that humans can understand it'. User manuals are just one of those things. I also write Release Notes, Knowledge Base Articles. I'm also asked to provide wording for dialogue windows that appear in our applications, or even just "hey, do you think this sounds right?" I'm the Company's 'Wordsmith'. I've taken on a bunch of responsibilities over the years, and some of them are really blurring the lines for me.

For example, as of late I've also been creating video promos for our applications - something I can do, but really has absolutely nothing to do with tech writing. To be honest, I'm really not happy about that last bit - but that's off-topic.

For HR to pose the question "What's a tech writer do?", it's akin to asking me to describe what an engineer does. Um... what sort of engineer?

It seems that there are all sorts of tech writers. For example, I really come from the perspective of teaching our customers how to use our software. And our customers aren't necessarily technically-minded - I need to have that hybrid mind that sits somewhere in-between nerd and layman. And that's me.

But there are other types of tech writer. I've discovered that there are heaps of 'tech writer' jobs where the employer is seeking candidates with a background in software development or QA. No offence to anyone out there, but I've yet to meet a programmer or tester who can document for a lay audience, making their role sort-of a contradiction.

So, back to my question: What's a tech writer?

I'd really like to get your perspectives. I'm not really looking for your actual duties, but your definition of what tech writing means. And yes, I understand that those concepts overlap. Perhaps we won't be able to avoid it.

[R Neil Haugen]

As someone on the autism spectrum ... an "Aspy" ... when asked such a question my highly analytical brain (I don't think it actually does anything but analyzes ... ) always comes up with the 500 qualifying queries ... do they mean this, or this? But is this a factor I should consider in the reply? And actually, X becomes a factor if what they want is this ... so ... I''ll end up giving a pretty "solid" answer. Lengthy.

Ever watched "Field of Dreams", the part where Kevin Costner's character has nearly forced James Earl Jones to go to a baseball game with him? After they get into the stadium, Costner asks Jones what he wants ... and Jones just goes off ... "I want to be left alone. I want all the freaking hippies out there to forget I ever existed ... I want .... " something like that, for a good thirty seconds of huffy response.

Kostner just points at the concession stand, and says, "No, I mean ... what do you want there?"

A very embarrassed Jones replies: "Oh ... um ... um ... dog & suds ... "

I (in essence) recreate that scene over and over for people, who are just as puzzled ... they expected a simple answer. Maybe five words. I gave them two long paragraphs.

I've learned to try and not over-analyze things, which ... is an issue. I don't always get the "obvious" subtext.

So ... all this is leading back to saying that I'd shoot back a query to the HR folks as to the format they wish the definition to be placed ... discrete sentences, paragraph/s, whichever ... and the approximate length of the typical description they use.

Technical queries, all with a good reason to ask them ... and from the answers, you'll have a much better idea if they just want "I write tech manuals and help materials and the occasional how-to video."  ... or something more defined.

Neil

[symmetricalMan]

Thanks for your response, I think?

To (attempt to) clarify, I'm not really asking for how I should respond to HR - it's more of a general discussion around what different tech writers feel is 'their job', compared with what the rest of the world thinks it is. If I do a search on LinkedIn for 'technical writing' jobs I get some very different ideas of what it is, in the same way an engineer could be defined as 'someone who designs bridges' by one person, and 'someone with a puffy hat who drives a locomotive' by another. The scope seems to have widened a lot since I got into it (around 20 years ago), as have the expectations by employers for a tech writer's duties and skill set.

An aside: We're all on 'the spectrum' - it's a scale, not a switch. 'High-functioning' seems to be common for tech-writing as it requires an analytical mind coupled with an ability to communicate. Nice to meet you.

[R Neil Haugen]

Ahh, but HR ... they're interested in how you respond!

"Tech Writing" ... that's really, what, about anything these days? Really.

So I do understand the attempt to define, to refine your role description, as things are so different. What I do within my own small business doesn't have hardly anything to do with anything I did twenty years ago. The tools of the normal workplace are so fluid, and to me more tech-based than ever. With so much coming at the typical worker (let alone their boss!) "we" need more and better tech info than ever.

And it needs to be in short, discrete, searchable chunks. Easily found, easily digested, easily ... replaced.

Easy job, right? Hmmm ...

One of my duties in my business is to essentially be the tech introducer, teacher, and writer. To distill tons of general information into the snippets which the others have time to digest, yet enable them to function with constantly changing software, hardware, and uses of those to serve our clientele. And to assist them to accomplish their tasks quickly, without error, and without supervision.

Neil

[pziecina]

One of my responsibilities, (years ago) used to include reviewing what tech writers actually wrote when it came to aircraft maintenance manuals. Reviewing the wording, the procedures described, and that any tech references where correct.

I also had to review training materiel, that was also written by tech writers, watch training videos, checking that the terminology and content was correct, and most importantly made sense.

So in order to answer your question -

It depends the product, so insert your own word(s) when required.

The tech writer is responsible for producing material that describes how the product works, how to use the product, and if necessary how to maintain the product.

This is done with the collaboration of various experts in the particular field being written about, e.g.

If the product can be broken down into various components, then an expert, (or experts if it can be broken down to the point it requires various specialities) in disassembling, checking, repairing, reassembling and testing, will check what and how it has been written, and advise of any inconsistencies and discrepancies.

In order to do this the tech writer must be trained, and hold a qualification if possible in the actual field they are writing for. For me that meant that if I was reviewing the tech writers instructions on how to carry out a ground test of an aero engine, the tech writer would have at least had some experience of doing so in the past, (though not necessarily for that engine) and would have written the 'how to' after talking and possibly watching someone doing the task.

To transfer this to say web development using Dreamweaver. I would expect a full and accurate description of how each function works, how I would set the program up ready to use, in various scenarios. How I would use the program most efficiently, (keyboard shortcuts, etc) and how I would evaluate that what I had done in the program, was correct and to the required standards. I would also expect a reference to any required reading that was required in order to carry out the task, (creating a web site with html, css and javascript would reference the W3C specs).

Any other requirements, say creating assets, (images video etc.) I would at least expect a reference to how to do this, and the requirements of the latest recommendations for doing so. So for images, a recommendation to a chapter(s) in a photoshop book, and a reference to any associated W3C specs.

I've almost certainly missed a lot out, but this will I hope give you an idea.

[Ussnorway]

I think the main point is to teach someone how to do something... and the difference between a good or bad is that the instructions are for that person and not just 'one size fits all' aka Microsoft textbook

[OldBob1957]

You have already hit on a portion of the way I've always described that part of my job for people:

-- I convert technobabble into humanspeak for the masses.

-- I make certain that the result is clear, concise and complete.

If a procedure is involved (and it usually is), I ensure:

-- That each instruction covers only one step.

-- That the instructions are in proper order.

-- That they are easy to follow.

-- That they are accurate.

-- That they are complete.

-- That if followed carefully, they will lead to the desired result.

The above description is generic, but that pretty well covers it for me. From there you can go on into specifics and knowledge needed for each particular field or sub-field. But the list above is the bare bones of the job onto which that information would be added. (IMHO)

Maybe I am over-simplifying, but you did ask...

--OB

[Ussnorway]

symmetricalMan wrote:

I'd really like to get your perspectives.

I would start looking for a new job mate... just a heads up

[symmetricalMan]

Here's what I've done in the past (and am expected to do) as a 'tech writer':

• Produce user manuals for our Clinical/Practice Management software. Step-by-step instructions. This covers the entirety of the work from start-to-finish, including any creating/editing of accompanying images (in Photoshop). These are produced in both CHM and HTML5 formats (I'm also responsible for the web site on which the HTML5 resides). We have 4 major applications I work on, and 4-6 subsidiary applications I'd work on from time-to-time.
• Produce 'Release Notes': a bullet-point brief of the changes in each software update, in PDF and HTML5.
• Beta Tester Release Notes: interactive PDFs of the Release Notes for our beta testers to complete - usually a lot more information than the standard Notes.
• Knowledge Base Articles: PDF and HTML5 formatted white-papers.
• Authorised Service Provider guides: (more Knowledge Base Articles, designed for ASPs - highly-technical info, or may contain 'sensitive' info). PDFs
• Interactive Tutorials: using Captivate or Camtasia.
• Proofing: I'm sent all sorts of documents to just edit/proof them.
• Wordsmith: I'm asked to produce (or re-write) wording for windows that appear in our applications, pop-ups etc.
• Admin Docs: format/produce interactive PDFs for Admin - things like leave application forms, requests for study assistance.
• Online Surveys: use SurveyMonkey to produce surveys for our Beta Testers to complete.
• Video Presentations: 30-second tute/promo videos of new features. I happen to have experience in music/video production - I have a little studio at home.

I don't consider the last five items 'tech writing', but I did/do them.

For me, tech-writing is about being able to learn a technology, and then explain it to others in written form. It's akin to training, but it's not training, really - it's just the producing of a training resource. I've been a trainer, and it's quite different, but the two fields overlap.

However, it seems that to be a tech writer now, you're also expected to be;

• a graphic designer
• a desktop publisher
• an editor
• a copywriter
• a trainer
• a UI developer
• a web developer
• a media guru
• a cinematographer
• a superhero. I'll be Iron Man please.

[pziecina]

The first 6 and last item in the first bullet list, i would say are your responsibility. But the last item only because you have experiance in doing so.

As for the second list, yes but i would not expect you to be an expert in these, if they are not necessary in order to fullfil the items in the previous list.

[Nancy OShea]

I often had to write my own job descriptions because nobody -- including supervisors -- knew everything I took care of.   They understood only what they saw personally but not the bigger picture.   So every 6 months or so, I had to revise my job description because it kept evolving.  I suspect your HR is doing the same thing, trying to get a handle on all that you do and what you do that perhaps you shouldn't be expected to do -- like the video stuff.

Put it all down on paper, keep a copy for your files. Also update your job description in the personnel file as often as needed.

Nancy

[symmetricalMan]

Yes, I've had the same experience. And yes, HR just want an update. I'm not worried about it - we're just going through the motions.

They've given me an idea of what they think my role is - what they think a tech writer does (not what they think my actual day-to-day duties are), but the description doesn't entirely fit what I do, or what tech writing means to me i.e. it reads like it would suite someone from a software development background who now writes low-level documentation suitable only for other programmers - like 'Developer Reference Guides', whereas my background (and current responsibilities) align more with the user experience - helping end users.

It's this that prompted me to post this question.

[Cactus_Cowboy]

Seems you been handed an opportunity here to either lighten your load or add to it. From what I understand through the years they've thrown more responsibility your way which you've tackled well but some that you'd prefer not to make a daily habit of. Hopefully you've been attuned to the direction that decision makers are taking in clients and where they seem to be steering the ship. Why don't you emphasize your strengths and areas that you enjoy doing and cut those you don't. If not expect more to be piled on your plate as they try to squeeze every last drop of sweat and toil out of you they can. And they will!

[Peru Bob]

Cactus Cowboy wrote:

If not expect more to be piled on your plate as they try to squeeze every last drop of sweat and toil out of you they can.

It seems as if it's already been done.