So Just What Does a Technical Writer Do, Anyway? And How?

[This is as comprehensive an introduction to the technical writing field as it gets. Although it's a bit too long for a blog post, it still makes a fascinating read due to its authenticity, high information content, and sincere personal tone. This is a tech writer who clearly knows what she's talking about. Highly recommended for all who are new to the field. -- Ugur]

By Barb M. Vega

I wonder how many times will I have to answer that question? “What is technical writing? What do you write? Where do you get the information from? Who do you give it to? Do you have to be a journalist/creative writer/poet/literature major to do that?”

And my favorite, the never ending questions on “How does the flibbertijibbet feature work in Word software?” (Which I frequently can’t answer because most of the true ‘heavyweights’ in technical writing use Framemaker for technical documentation!)

People come to technical writing from many backgrounds; most of us “fall” into it. We discover that, as in the case of writing for a software company, it pays pretty darn well (in California). Well, at least it used to before The Great Recession. Still, it is one of the few jobs you can get as a writer, and do it full-time and get benefits. That is not too bad.

I came to technical writing through teaching. And that is what I have discovered – that technical writing is most like teaching. It is the art of taking the complex, mastering it (yourself), and then breaking it down into easier-to-understand, manageable segments and pieces, so that others can understand it. It’s about being organized. Having a clear thought process – one that is logical, linear, and organized.

Most of my experience in technical writing is with software companies, which have their own nuances. So that is the type of technical writing I will discuss the most. I’ve done some of the other types – resume writing (yes, that is a form of technical writing), writing for engineering disciplines, and writing safety manuals (policies and procedures etc.).

All of these are forms of technical writing. In fact, business writing and technical writing are pretty much the same thing.

Essentially, technical writing is a non-creative, cut and dried type of writing, that does not need any creative lilt or flair. You just need an ability to analyze your audience, write to their level, learn the subject, dissect it into its component parts, and then start writing as though you were a guide leading others down a ladder – rung by rung, step by step. Sounds easy. And for people who have a knack for it, like me, it is easy. For people who don’t have a knack for it, don’t despair. There are some guidelines you can learn to get you started.

If you can, pick a software company that makes software you can really dig into. I mean, when you work with it, it feels like little brain teasers – little puzzles of modules to be mastered. I’ve found that if the software I am documenting is too easy, too boring, or just not interesting for some reason, I get stifled. Bored. Restless. I love finding a software that is a behemoth – whose codes have to be configured in advance to run it. If you’re really a tech writer wannabe, I can’t understate the importance of truly relating to and liking the software you are going to write about. It’s like a psychological thing.

Now to get started – There are myriad ways to get information. First and foremost, your company ought to put you into a training class to learn the software. Even if this is just a “taster” – and you’ll have to tinker with it on your own for months, there needs to be a training class.

After that, the best approach to writing is, try to answer as many of your own questions as you can BEFORE you go and bug the programmers to explain something to you. You will soon learn that programmers consider tech writers to be a nuisance. After all programmers are the “creme de la crème’ of the organization and have many more important things to do than talk to lowly pond-scum tech writers. (Ahem.) The best thing you can do for your reputation with them is to make your questions as minimal and discrete as possible. To do this, I would suggest cracking the software yourself. Play with it. Follow it. Read the help (if you’re lucky enough to have one). And while doing so, write down each question you have. Then you can go to whoever and show that you know all of this part, but there are just three or so things you don’t understand. That is a lot easier for them to swallow than you walking up to them and saying, “Teach me the flibbertijibbet module.” Trust me. They will appreciate this.

Yes, programmers don’t like to talk to tech writers. (Remember Tina the Tech Writer – on the Dilbert cartoon?) What you may do is, connect things with food to attract the programmers to you. Put a candy dish on your desk. This will assure that at least the programmers with a sweet tooth will stop by each day. Then you can hit them up with a question.

Now on to other sources of info. There is a maxim that says, the more people you talk to, the better your manual/help will be. Let me say that again:

The more people you talk to, the better your manual will be.

If you only talk to the programmers, you will get one point of view – one angle on the material. If you then talk to marketing, you will be shocked at the information you get – that you would not have and could not have gotten from the programmers. Then you move on and talk to the product consultants (also called trainers). These will be your best bet – anyone who is client-facing. They know how the software is actually used, what features frustrate people, where the design flaws (woops I mean features) are. They know what things the users find easy and what things frustrate them. The best information will come from the trainers. (They have to get up in front of the users – and they’re scared. So they know their stuff.)

Now, if you are lucky enough to have them, look at the training guides. The benefit of this is, where the help sometimes, often times I should say, gets behind, the training guides have to stay current. And the information in them must be “proven” accurate, because there is some trainer in the wings, having to teach with it, and, as I mentioned, not wanting to look stupid in front of a group of trainees. So they are usually amazingly on target.

Now you will want to look at the current help. Is it any good? Well, probably not. Most help is not that great. And there are reasons for this. The first reason is, in a software company, the tech writer is essentially a few levels higher than pond scum in most people’s minds. I’ve even heard it said (by a programmer -and Artificial Intelligence expert) that you don’t need documentation if the user Interface is designed well enough. Well that may be true for something like MS NotePad, but won’t work for industry software that requires hours of codes be set up to get the software to function. But look at the current help anyway. If it is good, great! Your job is not as difficult. But if it sucks, well, that’s still great. Because you should instantly see the things that make it poor. You should see how it needs to be improved because the very questions you have reading it are the questions the users will have. So you can start there – with the gaps that need to be filled in the current help.

The second reason help is often not great is that, well, good tech writers are hard to come by. Essentially you need to be a person who can handle technical material, but at the same time, who can write. If you have this combination of traits, then rejoice! You, like me, are a rather rare bird. If you don’t, well, to some extent you can develop them. But not too much. If you naturally just don’t write well you are probably not going to lift yourself up to a good level of writing with just a brush up.

Another reason tech writers are so hard to come by is that they are probably in another field – or at least in another type of company. Well, think about it. There is nowhere to go in the software company for the tech writer. It’s kind of like being an employee at a doctor’s office. You’re not going to be promoted and become the doctor. There might be some intermediate ranks in-between that you can get to (office manager, etc.), but usually there are not many. Tech writing is the same way. You will not be promoted and be a programmer, although you could possibly get into QA. You are never going to be the director of anything. The only higher-level position you can reasonably expect to hold is Documentation Manager – if there is one. (This position might be called Lead Tech Writer, Documentation Supervisor, or some other creation. And, aside from the pay, you’ll probably be doing about the same thing.) And this is if you’re lucky. At many software companies, there is just a tech writer and there is no manager of documentation. So as far as moving up? You’re s.o.l.

This is why for me, this was a great profession for just after I got married. It is largely heads down, low profile and it paid very well (at least in Southern California). It is usually relatively low stress and relaxing. You are a rather highly paid drone. You’ll never be the queen bee. So if you’ve just gotten married, or have small children it can be ideal (especially if you’re lucky enough to be able to work from home a few days a week.) But if you want power, and to move up in the organization, brace yourself. Or I should say don’t brace yourself. Because there is no promotional path for you. You won’t ever be the CTO.

A word about help, and how people feel about it. You will frequently hear it said about help: “The help is not helpful. The help doesn’t help.” And when I served a an Officer for the Society for Technical Communication (everyone who’s anyone in the tech writing field is a member) my colleagues all expressed the identical thing.

Now, why is that?

Well, aside from the reasons above, if you take a gander at studies done on help systems and user behavior with respect to help, you quickly learn that in general, user behavior is such that people don’t like going to the help. They don’t like to stop what they are doing and open a new window. It’s that simple. Call it inertia. Call it laziness. They want to continue looking at the part of the UI they are looking at.

So this is why of late, you have seen and will continue to see on an increasing basis, the move to “context sensitive help” – which is more recently termed “point of use help.” This is the little balloon that pops up when you hover over an item. Or, in better-designed software, there might be slideable panels, one of which is help, and that slides out when you click on an item, in answer to a question. All of this is the industry’s attempt to make the help go to the user, since the user doesn’t want to go to the help.  Learn not to take this criticism of help too much to heart. When your users say they can’t find things in the help, pick their brains further, at every chance you get, and incorporate their suggestions in to your manuals/help files. I have gotten some of my most inspired ideas from user feedback. But at the same time, when you hear the old familiar groan, “The help doesn’t help,” even after all you’ve done to make it sharp, don’t take it too much to heart. That groan is just an occupational hazard of the world of tech writing.

Speaking of the STC – I would suggest, at least in the early years of being a tech writer, that you get a membership. They put out some good articles in some great publications. This and the TECHWHIRL listserv (you can Google it). I can’t tell you how much I have learned on the TECHWHIRL listserv. There are tech writers on there from all over the world. You can ask a question and within an hour have so much information you will not be able to believe your eyes. You can instantly become an expert on a topic that you knew nothing about just the day before, because you have the benefit of dozens of emails from experts all over the world. And there are some real documentation guru’s on there. But one word to the wise; I would suggest going on there under an email pseudonym. The posts are Web-searchable. This means that your name, your company’s address information, and your question will be forever in searchable cyberspace. This can be a rather bad career move if your question happened to be, “I can’t stand my boss. What should I do?”

Do you know anything about document design? If you don’t, you should. There is a whole field of study devoted to type and layout, information design, use of graphics, and the like. Read up on the field of typography. You’ll be shocked to learn, as I did, that, for example, all caps actually decreases readability. And that you should be judicious in the use of color in technical documents. Black on white type is the highest contrast and therefore the most readable. Remember, this is technical documentation. Cold, hard, just the facts, ma’am. Your goal is not aesthetics. Your goal is to make it such that information can be found, retrieved, and absorbed in the least amount of time possible. Period. Not to wow people with colors. (Now I didn’t say to never use color. It is helpful for notes, tips, and warnings, for example.) But just be judicious with it – especially for body text.

Line length is another surprise. Have you ever seen documents with “side heads” (the headings start at the left margin, and the text starts at an indent?” Did you know there is science behind using side-heads? Shorter text line length greatly improves readability, because readers have to blink less during a line and are less likely to skip a line when they read. And there are other reasons too. The blank “whitespace” on the document opens it up greatly for the reader – is easier on the eye. I understand in the art field, this is called “negative space.”

And speaking of fonts. I know all the new fonts that come with your ever incrementing MS Office suite are dazzling, but technical documentation is not the place to try out every new font, on each of the headings. The last thing you want to do is make your document look like a ransom note. Try to limit your documents to having no more than two or three fonts. And if you read the NYT book you’ll learn the difference between serif and sans serif fonts. A good rule of thumb is to make the headings a sans serif font (Arial is the most common) and the text a serif font (Times New Roman is the most common.) And don’t forget about your users over 40. They will thank you for make the Times New Roman font no smaller than 11 (10 is fine for sans-serif fonts.)

A word about Word. The truth is, the real “heavyweight” tech writers don’t like to use Word for documents. Well, OK, some do. But they are the minority. When you really become a tech writer heavyweight, you can, should and must learn Framemaker (Adobe). Get a copy of the software, if you can (sorry, it ain’t cheap) and if your current employer does not have it fight like mad for them to buy it. It does things that leave Word in the dust – things that non tech-writers have no appreciation for – like multi-nested numbering, alternate headers, sub headers and footers on front and back, odd and even pages. Word will choke on these and will drive you nuts if you have to sit there all day doing long documents. And Frame won’t balk at tons of images – nor will they move around when you open the software on a different computer, or when you print the document off on a different printer. These things sound small – and are small for the user who typically uses Word just to write a document, memo, or letter. But when you are working on a 100 page document with conditional text, and with auto numbering on all graphics, chapters, and pages – yikes. Word will drive you absolutely batty. Now the learning curve for Frame is long. But once you learn it you will defend it to the end. Trust me. In fact, when I read a tech writer job ad and it says they use Word, I automatically move on. I just don’t consider them to be an able shop.

Now, as far as doing online help – the old standby is RoboHelp. It’s been around for many years, and is the new iteration of the old ForeHelp, which was bought, then bought, then bought, then bought again. But there are many other good ones out there now. Flare, by MadCap is actually programmed by a large number of the ex-RoboHelp programmers – so you may try that package instead of Robo. Robo has been off-shored to India; when Adobe bought RoboHelp many jumped ship and formed another company, MadCap. So you may find Flare much more to your liking. There is also Doc to Help (easy to learn – has a lot of good features) and a few others.

Don’t be afraid to be repetitious (to an extent) in this type of writing – technical writing. You may find yourself writing, many times “To do nnn, follow these steps:”, or “From the nnn menu, click mmm.” It’s ok – and actually desirable -to be repetitious in this type of writing. It helps the reader know what to expect. Minimalist writing is key – use an economy of words. This is not the time to emulate Hemmingway. Just get the information to the user in the easiest, simplest way you can.

Can you take criticism? I hope so if you want to be in this field. Your work will be visible to the whole world. Everyone in the company – everyone outside of the company. And trust me, everyone will have an opinion – good and bad. One thing you absolutely must have in this field is a thick skin. When you finish your draft and hand it to the programmers for review, don’t get upset at revisions. You truly have to get used to saying “Ok thanks. I’ll get these changes in.” Remember, it is not personal. It doesn’t (necessarily – at least it shouldn’t) mean you are a bad writer. First of all, it’s been shown that when you write something, you can’t see your own mistakes – or ways that something might have been said more smoothly. It has something to do with the right brain versus the left brain. It’s been proven that another person, another pair of eyes must review it. Otherwise you will simply not see your errors.

A fresh pair of eyes will catch things that you won’t. Typically, when you catch your own mistakes it will only be several weeks after you wrote it. In fact, over your years of being in this field, you will notice a curious thing. Each time you read something you wrote several months ago or more, you will find things to change. You will ask yourself “Oh boy. Did I write that?” I understand the same phenomenon happens with programmers. Many have told me that when they see code they wrote let’s say a year ago, they ask themselves “Boy, did I write that? I can see a better way to do that now.” I suppose it’s that left-brain right-brain thing my Master’s degree professor told us about.

Overall tech writing can be a blast if you’re the right person for it. Give it a try. You’re the only person who can make the final determination as to if this field is right for you.

About Author Barbara Vega:
Barbara Vega is a writer living in South Florida. She is married, with 2 dogs and a cat. She is published, has done textbook review, and holds a degree from the prestigious University of Pennsylvania. With over 13 years experience, she is a noted expert in the fields of technical and grant writing.