Technical writers go by a lot of different names nowadays. Many us of like to be called “technical communicators.” Whenever someone asks us what a technical communicator does, our facetious answer is “We write the manuals that no one reads.” The serious answer, though, is that technical writer communicate information vital to someone’s proper use of software, hardware, device, or gadget.
But there’s more to it than that. And this article offers one of the better explanations that I’ve read of what a technical communicator is and does.
If you’re a technical writer, then chances are that you have to create online help. And that’s where the fun begins. You need to choose the tool that’s right for your purposes, which can be a tough task.
This article (and its follow-ups: here and here) offer a nice overview of the available help authoring tools out there. You get the major pros and cons of a number of applications, from the big guns — like Flare, RoboHelp, and AuthorIT — to lesser-known tools — like ReWorx and HelpNDoc.
One mantra that we continually chant is “Write tightly. Write tightly.” Tight writing and proper streamlining not only makes documentation easy to read, it can help make it more usable.
If you’re interested in making your writing tighter, read this article. It contains several useful tips on how to effectively edit your work. Once you internalize this information, you’ll find that you will automatically apply the principles.
Do you find yourself scratching your head when you run into software error messages? And, as a technical writer, do you want to do your bit to make those messages more meaningful? Read this article for some great tips on crafting meaningful and effective error messages.
When it comes to screen captures, some technical writer work on the premise that a picture is worth a thousand words. Unfortunately, the thousand words that a picture can convey are only meaningful if they have a context.
Unfortunately, in many cases screen captures are used as eye candy — they do little or nothing to enhance the text that they accompany. They’re inserted, for example, to break up long blocks of text. Or, they’re used to make up for a perceived paucity of information in a section or a procedure. Some writers throw screen captures in just because they think the images are needed. More often than not, they’re unnecessary.
Screen captures can be useful. But they should be used sparingly. Here’s some advice on when to use and not use screen captures:
- Don’t include captures of every screen in an application. Doing that takes up space, and adds no additional value to your documentation.
- Use a screenshot to illustrate how to use a section of the user interface that may not be intuitive. For example, if you have a configuration dialog box you can include a screen capture that includes sample input.
- Screen captures are useful when illustrating something like a generated report or graph. However, if (for example) the application that you’re documenting has 20 different reports, don’t take captures of all 20 — just include an example of one report in the overview section for that chapter.
- If you need to use screen captures in online help, try not to take up screen space with them. Instead, include a link to a pop-up of the example screen wherever and whenever possible.
Several years ago, I was part of a team documenting a fairly complex suite of telecommunications apps. One day, while working on a particularly thorny section of a manual, one of my colleagues turned to me and said “Are we supposed to understand this stuff?”
While I’ve met quite a few writers with strong technical skills and knowledge, I’ve also found that the attitude expressed by my former colleague isn’t uncommon among technical writers, of any level of experience. Remember that in title “technical writer” the technical part can often be just as important as the writer part.
I’ve always believed that to be an effective technical writer, you need more than knowledge of the tools of the trade and to be able to write. You need a good grounding in the software, hardware, and technologies that are used by your employer. Maybe not to the level of the system architects and developers, but more than a cursory knowledge. And if you don’t have that knowledge or those skills, you should be willing and able to learn — either by taking courses, reading books, or asking a lot of seemingly dumb questions.
For a longer take on this topic, read this article at techwriter.dk.