A recipe for technical writing

Before I walk you through my process of writing technical documents, let me start by saying in general there are three aspects to all written communication:

Structure: the way the content is laid out
Style: the way it is written, or the language used
Content: what you are writing about

The following is an outline of my technical writing process. Obviously, this is not the only way to write technical documents, it’s just my approach. Note that I don’t always follow this recipe to a T, and I don’t always follow it in the exact order shown below.

Recipe

Plan what you want to communicate before writing. Jot down the following things:
1. Purpose of the communication
2. Identify your audience and what information is important to them
3. Your initial, important thoughts as a bulleted list
Create the outline/section headers (structure)
1. Arrange the list of thoughts into a logical sequence with a:
  1. Beginning (introduction) – should clearly state the subject and purpose
  2. Middle (content)
    1. Ground your content in facts: If you are going to tell what you think, give a solid reason why you think it – don’t assume the reader knows it.
    2. Don’t let details obscure the main issues.
    3. The content should be positive and constructive.
  3. End (conclusion) – Should summarize what you want to communicate and identify any remaining issues and what needs to be done to resolve them.
2. Help key points to stand out by the use of headings and sub-headings. Headings and subheadings should be selected carefully and should give your readers a clue about what they are going to read. Keep the headings and sub-headings short. Even if the section headings are not desired in the finished piece, they still help you as an author to structure your writing.
Convert the outline and bulleted list into a first draft
1. Sections
  1. Put the most important information in the first paragraph.
  2. Pictures are worth a thousand words. Use diagrams where possible.
2. Paragraphs
  1. Keep to one idea per paragraph. Each paragraph, excluding the introduction and conclusion, is devoted exclusively to a particular sub-topic in the piece.
  2. Limit paragraphs to a few sentences. Paragraphs of less than 10 lines are easier to read.
  3. Besides the very common words, try not to repeat the same keywords over and over again within a paragraph. It gets repetitive and doesn’t reflect well on your vocabulary. Most text editors these days come with a built-in thesaurus. Don’t hesitate to use it.
  4. Ask yourself the following questions after writing each paragraph:
    1. What am I trying to say here?
    2. Could I have put it more shortly and more clearly?
    3. Does it flow well?
    4. Have I said anything that is unnecessary or not clear?
    5. Have I said anything that will upset the reader?
3. Sentences
  1. A sentence should convey a single thought.
  2. A sentence should be able to stand on its own. Avoid the use of an incomplete sentence.
  3. Keep the sentences short, no more than 15 to 20 words, but they shouldn’t be choppy. Remove unnecessary words. Words such as very, just, quite, perhaps, maybe, and really should not be used. Sentences with more than 20 words should normally be split.
  4. Break lengthy information into bulleted lists.
  5. Never use the passive voice (“Bones are liked by dogs”) where you can use the active voice (“Dogs like bones”).
Complete the first draft by carefully checking spelling and punctuation
Iterate, improve, revise
1. Accept that the first draft is almost always crap. Even the best writers have to spend a lot of time reworking material to make it simple, clear, and direct. Be tough on yourself, and learn when to delete or rework something.
2. Always read and review what you have written. Edit the document through several revisions, honing the text until it is just right.
3. Strive to explain and make things a little bit clearer.
4. If it is an important document, leave it overnight if possible for your mind to reassess it.