Documentation has been dear to me for a long time. Its usefulness and importance are immense. Here are some of my thoughts on doing it well.
- Keep it simple. Documentation should be brief and to the point. Have economy of words and do not spend them easily. Simple bullet points go a long way. Use plain language and short sentences.
- Write in English. Even in an entirely non-English shop, write in English. You never know when you will expand into a neighbouring country, or work with a consultant who only speaks English. Google Translate will not cut it.
- Screenshots and video are not a preferred way to document. They can complement existing documentation, but should not be your only documentation.
- Do not document by copy-pasting whitepapers. Only do it when it is a perfect fit for purpose. Otherwise link and reference the material rather than copy it.
- Capture the essence. Make it as simple as possible to read and understand. Economy of words gets you a long way.
- Never include passwords. Sensitive information is usually fine, since the documentation should sit behind access restrictions, but passwords are not. Passwords change regularly, so store them in a password manager, not in the wiki. I have written before about why you should be using one.
- Make documentation a business requirement. Do not let systems or services go live without at least simple documentation available. It takes little time to set up some scaffolding and add the essentials.
- Keep the platform available, fast, and easy to use. A wiki such as MediaWiki works well. If documenting is tedious and hard, it will not happen. Trust me on this.
- Knowledge is power, so people hoard it. Many avoid documenting to stay valuable to the business. Do not be that person. It gets noticed quickly, and any thriving business wants to keep good employees. Documenting builds a healthier organization and keeps you around for the end game.
- Do not get stuck on the same repeatable tasks. Write good procedures so that next time someone else can do them. Spreading knowledge frees you to move on to more challenging work.
- Keep your documentation tool always ready. Whether it is a notepad or a wiki, keep it signed in and open. The moment documenting is not trivial, you will skip it.
- Do not wait until the last minute. You will forget what you did. Write as you work. If you had to redo part of a setup, just go back and edit the step that changed.
- Keep it fresh. Stale documentation is bad, and wrong documentation is worse. Make it simple and easy to update.
- Not everyone is an author. You still need to write something. Keep it readable and understandable, and refer back to tip 1.
- Avoid repetition. Duplicate information is a no-go, because it is a hassle to update in multiple places. Use your platform’s features to include content from a single master source.
Got tips of your own? I would love to hear them.