Lately I’ve been writing a lot of documentation, instructions, and guides for work, Hackster.io, and my side-project (Open Smart Hub). Most of the time the instructions needed to be compiled from multiple sources but kept simple and digestible. As a long time consumer of documentation, I’ve come to a couple realizations about instructions and guides. The most important is:
Make it dead simple. It should be fool-proof and easy to follow.
Don’t make assumptions about a reader’s skill level, the more knowledgable readers will skim over the instructions they already know, but newcomers will treasure those details.
- Draw up a storyboard of the steps. Just like primary school, where they would tell you to brainstorm on a sheet of paper before writing an essay. This will help you figure out if there are any missing parts before you get into the nitty gritty details, whether or not the ordering makes sense, and if you need more research as well.
- Start with a schematic of the parts (if it’s a hardware related or multiple component documentation)
- Add pictures (these always help clarify for the unsure)
- Be concise. Make sure that each word added to your documentation adds value.
- Don’t overwhelm your reader. (Avoid using acronyms unless you have elaborated on them earlier in the documentation)
Making this kind of robust yet straightforward documentation takes time, but it will also reduce the amount of support and questions you might receive about it in the future.