Just because I don’t talk about documentation much doesn’t mean I’ve never done it. And usually when people hear the term “technical writer,” that’s what they assume that you do. So what is documentation and what’s the job like? Let’s take a look.Types of documentation

There are several types of documentation; I’ve done two of them: requirements and user documentation.

Requirements

This is the type of documentation developed when a team is determining whom a product will serve and what it will do. It will include listing the users and how they would use they would use the product, and for what purpose (also called use cases); a definition of the overall system architecture and development methods; a description of how the development team will do its work  (what will be developed first, what might be added as additional features if there is time/money available); a schedule showing how long the development process will take; a concept of operations for using the product; a lists of participants, roles, and responsibilities; and eventually detailed descriptions of the data to be acquired and how it will be manipulated.

The audience for design documents of this sort are often information technology managers, who want to ensure that a development team knows what it’s doing, that resources are being used wisely, and that the work is proceeding according to plan.

Many types of engineering–such as my favorite, launch vehicle propulsion–use requirements documents to make the design process more systematic and to ensure that everything has been accounted for before people start coding software or “bending metal.”

Technical Documentation

This is the serious, in-the-weeds documentation that communicates, engineer-to-engineer, or engineer-to-manufacturer, how things should be designed or built. Unlike requirements definition, which can be done without a lot of formal training in an engineering discipline, technical documentation usually requires hands-on experience with the tools, hardware, processes, and terminology needed to do the job. I had to turn down a software documentation job because it would’ve taken much too long for me to get up to speed.

These are the types of jobs that often go to “engineers who can write” (don’t laugh, English majors–they exist). For example, if you see a technical documentation job that includes in its experience requirements time spent in the military or an engineering degree, they are looking for someone who can write engineering content by engineers, for engineers. This is not my thing, needless to say.

End User Documentation

This is the type of documentation most people are familiar with. It’s the book or online help module that people refer to when someone tells you to RTFM (“Read the Frickin’ Manual!”). It’s a step-by-step process document that walks a user through the process of operating or employing a piece of software or an engineering product like a toaster or, yes, even a launch vehicle. User documentation often employs a dual-form organization, meaning it’s broken out by function, but is chronological when describing individual functions. It includes possible cautions and warning, which appear before a step is taken so the user is aware of a problem prior to taking any action. It establishes technical nomenclature and provides a glossary of those ever-present acronyms. It also ties the product’s functions with work functions.

To write user documentation, you  have to become familiar with the user’s actual work processes: what their primary tasks/outputs are; how they normally encounter the product (are they at their desk? on a factory floor? in a machine shop?); how often they are likely to use it; how dangerous errors are if they occur and how they can be addressed; how do they handle exceptions or unusual situations; and what personal safety equipment (if any) they are likely to require to handle the product. In the space world, a payload user guide would tell a prospective payload manager about how they would go about delivering their payload to the rocket manufacturer, what sorts of interfaces they are likely to need, and what types of environments their payload is likely to experience during launch, and so forth.

User documentation is the supreme example of “translating Engineerish into English” and is often the most challenging and people-intensive technical writing you might do, as you must be able to absorb what the engineers are doing; advocate for the user if the product is creating problems, confusion, or dangers; exercise diplomacy when challenges arise between the designers/developers and the end users; write user test cases that make sense for the users’ work environment; operate as a guinea pig (test subject) for the user test cases; and keep the documentation updated as product/version upgrades arise.

Is documentation writing for me?

I hope the definitions above are helpful. As you can see, documentation requires a broad set of skills and knowledge, both technical and soft-skill related. It’s challenging, but it can pay the bills nicely.