Technical Writing 101: What do technical writers do?

by John Hewitt

“I thought you guys just wrote stuff down.” – A project manager after hearing what my documentation group needed in order to complete a project.

Technical writing is not like most other types of writing. To begin with, you may or may not spend much time writing. The majority of my time is spent reading, researching, and going to meetings. The writing part is straightforward. The main writing goal when creating a technical document is to use the simplest and clearest words possible, and to use them the same way every time. For example, if you write “Click the OK button” the first time, you write it exactly the same way the second time. You don’t write “Click on the OK button” the second time, even if it means the same thing. Simplicity and consistency make it easier for people to follow instructions and to understand information.

The advantage of such straightforward writing is that once you get used to writing in that style, it is easy to do. The hard part of the job is figuring out what information or instructions to provide. To write about a product you need to either understand that product yourself, or you need to have source material that gives you the information you need. Acquiring information and knowledge is the part of the job that takes up most of your day. If you find it difficult to learn new things quickly and independently, technical writing is probably not the job for you.

Information is gathered in the following ways:

· By using/testing the product yourself

· By reading source material such as technical specifications, business requirements and legacy documentation

· By attending meetings that discuss the product

· By interviewing Subject Matter Experts (SMEs)

· By conducting independent research (Google, Wikipedia)

· By having qualified people review your document. Sometimes, the best that you can do is to make an educated guess and hope that the people who review your document catch any errors. Is this ideal? No, but it happens.

Here are some typical documents that a Technical Writer creates:

Datasheets: A datasheet is a list of key information about a product, component or system. A datasheet is usually a single page but it can run longer. Datasheets consist of facts such as features, configuration options, part numbers, testing codes, known issues or limitations. These documents contain very little writing, but are often put together by the technical writer as part of a larger project.

FAQs: An FAQ is a list of answers to frequently asked questions. In many cases, these are really anticipated questions because the product has not come out yet. An FAQ can cover virtually anything about a product, but usually it deals with questions about how to use the product, what the product accomplishes, and solutions to problems the user might encounter.

Help Files: Help files are information files that are accessed using links from within a product. Any information file that you access via a link from the product is technically a help file, but most help files are step-by-step instructions or explanations of key concepts and features. In some cases the help is context sensitive, which means that the linked file will specifically address the question the user is most likely to have from that location in the application. In other cases, the help files are a unit, and the link the user clicks on sends them to a directory of help files that they have to navigate through using keywords, titles or searches.

Installation Guides: An installation guide provides step-by-step instructions for installing a product (such as software, hardware, a car stereo). The guide might also identify prerequisites, configuration options, and advanced features.

Quick Starts and Quick References: These are short documents (often designed to go on the front and back of a single sheet of paper) that provide a concise list of features, concepts, and instructions. These documents are designed to give users enough guidance to get started with the product without having to read through an entire manual. In many cases, this is the only document anyone reads.

Reference Manuals: Reference manuals provide in-depth information that is beyond the scope of an introductory guide. A programmer’s reference manual, for example, might contain sample code, lists of variables, lists of error messages, and in-depth explanations of features.

Release Notes: Release notes are designed to update users on new, altered or discontinued product features for a new release of an ongoing product. Most release notes are simply a list of changes, although in some cases these documents are used for marketing and take on a more sales-oriented tone.

User Guides: A user guide provides the information that a user needs to understand and operate the product. User guides consist of explanations of key concepts and features, navigation assistance and step-by-step instructions. Some user guides also have installation information, but often that is a separate document.

Ninety-five percent of my work has been on the types of documents I’ve just described, but this is by no means an exhaustive list of the documents you might create. Some of the other possibilities are Service Level Agreements, Standard Operating Procedures, Process Guides, Training Manuals, Flowcharts, Project Plans, White Papers, Wikis, Administrator’s Guides, and Technical Proposals. There are occasions when you might even get pulled into the marketing department and find yourself writing some sales materials. One of the traits I have found useful over the years is adaptability. You never know what you may have to learn next in order to do your job, but if you are a technical writer, you can be pretty sure that there will always be something you need to learn.

John Hewitt is the publisher of PoeWar.com, which has a variety of articles about writing, including technical writing.