Inspiring

Question

Define "Technical Writer" - your thoughts?

Forum|Forum|9 years ago
January 31, 2017
5 replies
1746 views

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.

This topic has been closed for replies.

symmetricalManAuthor

Inspiring

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

Legend

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.

Ussnorway7605025

Legend

symmetricalMan wrote:
I'd really like to get your perspectives.

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

OldBob1957

Inspiring

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

Ussnorway7605025

Legend

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

R Neil Haugen

Legend

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

Everyone's mileage always varies ...

symmetricalManAuthor

Inspiring

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.

pziecina

Legend

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.

Sign up

To post, reply, or follow discussions, please sign in with your Adobe ID.

Sign in to Adobe Community

To post, reply, or follow discussions, please sign in with your Adobe ID.

Scanning file for viruses.

This file cannot be downloaded