Writing Good Documentation
28 September 2016, by Chris Arnott
There are certain standards that govern good design and user experience. But eventually we all need to do something out of the ordinary or sufficiently complex that it will be accompanied by documentation. I’m not talking about the comments you leave in code (that’s a whole other kettle of fish). I am discussing the big document you have to write, which explains the nuances of your API, and how best to use your shiny new touch gestures.
If you think it’s almost as boring writing these documents as it is reading them, then I say you’re doing it wrong!
If you read on, I’ll explain what you should be thinking about before writing any documentation, and how this will help you enjoy the writing process more, as well as ensuring the end user gets the most from documents you produce.
There are three main things that you should consider when writing a document. These are Vision, Structure, and Level of Detail.
This is the most important point to remember. Why are you writing the document?
If you cannot answer that, maybe you should not be writing it at all. Once you know why you are writing it, you will also know who the target audience is. Use this knowledge to pitch the document at an appropriate level. Try to see the document from their perspective. What do they want to get out of reading the document?
Once you know these things, you should think of some example tasks that you’re audience will want to be able to achieve once they’ve read the documentation. How will they know where to look in the documentation to achieve these tasks?
Structure – Start with the headings
Subheadings – Should be filled in second
- Thirdly, put in some lightweight bullet points for each section.
Finally, after you’ve got the skeleton structure in place, go through and expand everything out with full text.
There are two main benefits to defining the structure of your document first.
- Primarily, it will enable you to keep the vision of the document in mind while you define the structure. This ensures the structure is well suited to your audience’s requirements on your document.
- It also has the added benefit that, on a multi person team, you can delegate filling in the details to different people.
Level of Detail
It’s important not to go into too much detail when writing your document. If you do, you’ll be wasting your time writing the detail, and your audience’s time in having to wade through the detail to get to the crux of your information. If extra detail would be beneficial to some users, reference other documents rather than cramming too much into your document.
So what have we learnt? Well, if you want to write a good document:
Answer these questions before you write anything:
- Why am I writing this document?
- Who is the audience?
- What do they need to know?
- What will they get out of reading this?
Then structure your document:
- Write your headings
- Write your subheadings
- Write bullet points around the content
- Add in any diagrams
- Fill out the detail
Ensure that when you get to step 5, you don’t go into too much detail.
Categories: Soft skills