Documentation

How to Write Instructions §

Writing instructions in general is actually a lot harder than it seems. It can be tedious, boring, and even make your head hurt. And it can take forever.

But it’s worth it:

• You will become even better at this task.
• You can have other people do this task (yay!).

Below is the process I go through:

flowchart TD
    A(Learn and practice task) --> B(Document ALL steps)
    B --> C(Step away for 2+ days)
    C --> D(Read and edit)
    D --> E(Do task using documentation)
    E --> F{Are you happy with the documentation?}
    F -->|No| D
    F -->|Yes| G(Add key sections to documentation)
    G --> H(Peer review)
    H --> I(Someone uses documentation)
    I --> J{Did they get stuck?}
    J --> |No| K(Ongoing maintenance)
    J --> |Yes| L(Read and edit)
    L --> I
    K --> K

• Learn and practice how to do the task you are writing instructions for.
• Practice, practice, and practice until it seems like for the most part you have seen and encountered all of the possible issues in getting the task completed.
• Did I mention you need to have done this task over and over and over.
  • OK, I think you get the point. Your job is to hand over this document to someone who has never done the task and they will be able with just using this document, complete the task.
• Document ALL of your steps the next time you do this task.
  • The moment you skip a step, this is when the person reading your instructions will get stuck.
  • Yes, even document the obvious steps, and the steps that rarely happen.
• After the document is written, re-read it from the beginning to the end to see if you missed anything or if something was not written clearly.
• Put the document away and don’t read it for at least a few days.
• Read it again and see if what you wrote makes sense.
  • You will notice that after you stepped away from the document and read it again, there will be things you are going to change.
• The next time you perform the task, use your instructions.
  • Follow the steps exactly like you write them and see if the instructions you wrote actually work.
  • If you skipped a lot of steps, you will quickly notice someone new to this task will be lost real fast.
• After you feel that the instructions will get someone else to complete the task, you can then add these sections to your document
  • Introduction
  • Background
  • Links to files/folders/applications/tools
  • Summary of the steps to complete the task
• Send the instructions through peer review.
• Now it’s time to test your instructions. Actually have someone do the task using your instructions.
  • If they get stuck in a step, update the document so that step is not confusing anymore.
  • After after you explain what they need to do, ask them how they would have wanted you to write it in the document. This will help you re-write this step.
• Ongoing Maintenance
  • As other people use your instructions, they will get stuck at different steps. Just repeat the process and make those steps easier to follow.
  • Tasks change overtime, update the document to reflect any changes in the process.