15 Steps to Write a Technical Document

published on 14 March 2022

Writing is a process. Toward the end of the process a document emerges. That's the outcome. Live the process and trust that the outcome will happen.

Step 1: Identify your audience

Find out about your audience. What's the smallest viable audience? What do they do? What do they need to know? How much do they already know. Plan your document for someone; not for everyone. 

Think about the “why” behind what you want to write about. What's your audience's purpose for using this document. Think of the ending and then work backwards from there. 

Step 2: Assess the complexity

Could you explain the feature to someone in a few minutes?

Will the reader encounter any “unknowns”? Can the reader easily find out the unknowns? 

Know the complexity of your writing project beforehand and set realistic expectations.

Step 3: Write a purpose statement

Describe the premise of the document.

Mention the type of document—getting started guide, tutorial, API reference guide, release note, README, and so on.

Write what the document does. For example, 'this section describes .. for a developer to configure...so that...'

Step 4: Research and test 

Use your purpose statement as a tool to drive your research.

Do an extensive internet search. You’ll be surprised at what you discover. Jot down notes as you research. The goal here is not communication; it's compilation. At this stage, you should be able to converse with an expert about the subject. 

Test the feature. Make sure you understand exactly how it works. As you find information, think about how to communicate it to others. Knowing what to write is half the work, actually writing it is the other half.

Step 5: Gather all info

Gather all available information in one place. Notice connections. Identify sections. See how they relate to each other. Use this to organize your material.

Step 6: Remove the noise

Go through all the info that you've gathered. Keep what matters and remove what doesn’t. Everybody has access to information. Your expertise is based on curating information. 

Step 7: Come up with an outline

An outline is a list of the main points that you want to cover in the document. It's the blueprint that you'll use to build the document. Keep the outline at a high-level.

Include sketches, charts, diagrams, shapes, and arrows. Lots of arrows. Visual markings spark creativity. Compare your outline with your purpose statement to make sure it's all relevant.

Step 8: Transform info into a draft

You need to start filling in the details for each point in the outline.

Start drafting the body of the document first and then the conclusion and finally the introduction. After you write the body, coming up with the conclusion and introduction is easy. Burn through your first draft. Write it down as fast you can. Don't fuss over the sentences. This is not for people to read. Turn down the voice of your inner critic and just keep going. Make a note of all your doubts and questions.

Step 9: Interview SMEs

Schedule meeting with SMEs to go over your open questions. Don't script all your questions. The most interesting bits of information are what you don't expect.

Say "wait" a lot. Slow down the conversation until you clearly understand what's being said.

Record your meetings to listen to again.

Step 10: Organize your draft and check accuracy

Organize all your topics logically kind of like a story.

Make sure the content in each topic is technically correct.

Step 11: Edit for coherence

The idea is to make the logic of the document more obvious.

Repeat keywords and be consistent when you use terms. Repeat your topic names within the text.

Begin each topic with a sentence that summarizes the main point of that topic. Repeat your topic names in the text.

While editing for coherence, make sure to:

  1. Use lists. Introduce the list and make the list items grammatically parallel.
  2. Use transition words like 'however' and 'because.'
  3. Use diagrams to teach. Introduce the diagrams to tell the audience what they're going to learn. Label the diagram. Explain the diagram.

Step 12: Edit for clarity

Make sure every sentence has just one interpretation. 

Step 13: Edit for economy

Cut down on all unnecessary words:

  • at this point of time -> now
  • In the event of -> if
  • Marcom is responsible for the submission of invoices each month -> Marcom submits invoices each month
  • In order to meet the objectives of this test -> To meet the test objectives
  • which is composed of -> composed of
  • complex and challenging -> complex

Step 14: Edit for readability

You can use software to calculate the readability score for your text. Typically, the score must be less than 7. To improve readability, replace long words with short words and reduce sentence length. To learn more, see 10 Tips to Write Better Sentences.

Step 15: Advance iteratively

Revise, revise, revise, and revise some more. Step away for a while. The breaks are part of the process.

When you finish the draft, you'll feel the satisfaction for finishing it.

Read more