How to write technical documents first depends on the kind of technical document you’re writing. This is the biggest factor in deciding tone, style, word usage, etc. Most of the technical documents I write are user guides (UG), or Best Known Methods (BKM). Both types of documents save your reader’s time and energy, and can make the difference when launching a product or training session.

User Guides or Manuals (UM), tend to be longer, more complicated, and have more references. They generally deal with product specs, building instructions, and the like. The longest UG I have worked on was over 4,000 pages, the shortest are less than ten. They all follow the same basic steps:

• Introduction
• Body of the Text
• Tools Needed (if applicable)
• Steps (usually with Images)
• Final results
• Conclusion
• Appendix with resources (if applicable)

Then it is up to you, the writer, to take all that information that you have tested, or have been given, and make it into something that the end user is able to read.

How do you do that? You KISS* (Keep it Simple, Scribe**). Think about who your audience is, a skill that is always important when writing. When I write, I imagine that I am producing documents for my grandparents or my friends who are ESL speakers (English as a Second Language). English is a tricky language, and a technical document is complicated enough without translation issues. Avoid turns of phrase and spell out all acronyms the first time they are introduced. Don’t take for granted the things that you know, they may not apply in a different language.

Another neat thing about writing UG/UMs is the fact that you can get away with publishing a whole document without a single complete sentence. In fact, bullet points, numbered lists, and notes are your friends in technical documentation. Bring on the sentence fragments! Use tables and images to illustrate the instructions. This is a situation where a picture is really worth a thousand words, and visuals are easier to understand.

When it comes down to it, the document is a more detailed version of “put the thing in the other thing and turn it on,” or some variation of that idea. If you can get that message across to the users, you’ve done your job.

I find that BKMs are easier to write. Usually, when you’re writing a BKM it is for an internal process that you work on regularly. Examples of BKMs are: instructions on posting a document to an internal portal, how to run a machine, or how to process software testing. Even if it isn’t something that you work on personally, you should work closely enough with the person giving you the instructions to complete the final project. If you feel like you don’t have enough information, talk with your manager/engineer to fill in the blanks.

BKMs work best with clear instructions, small words (unless they are process specific), and diagrams. Think about trying to put IKEA furniture together without the diagrams. My house would be filled with nightmarish semblances of furniture. These documents are often shorter than a UG, usually less than ten pages. The writing process is very similar:

• Quick introduction, less than a paragraph.
• Steps for the process, including sub-steps, diagrams, tools needed, and images.
• Conclusion/Summary of the final product.

Right now you may be wondering what the difference is between a User Guide and a BKM, which is understandable as they are similar. Think of a User Guide as the full explanation and possibly a little history of the project, whereas a BKM is a quick “how to.” Essentially, the two documents cover the same basic ideas, but the detail they get into differs. Remember: always keep your audience in mind. User Guides often go to external users (a wider audience) and BKMs tend to be internal (a smaller audience).

Technical writing is much like any other style of writing; you are passing along information to your readers in the clearest way possible.

• Bullets, notes, and number lists are your friends.
• Add images whenever applicable, the entire document can be images with minor text notes if that’s what works.
• Keep your audience’s technical knowledge in mind.
• Spell out acronyms the first time they are used, and consider adding a table of acronyms if the document contains more than ten.
• Use tables to keep track of test results.
• Don’t get fancy with your language. The document needs to be readable, not pretty.
• Commit to a positive relationship with your engineers/testers, this will make your job so much easier. Tech guys tend to like cookies, just an FYI.
• Most of all have fun with it. Even technical writing can be enjoyable if you keep an open mind. Proof-positive: I love my job.

*Tech Writers LOVE acronyms, seriously we can have whole conversations in them.
**Traditionally, this ends with Stupid, but I think that’s rude and ablest.