Documentation has been very dear for me for a long time. The usefulness and importance of documenting is just so immerse! In this post I’ll take a chop on some of my thoughts on documenting.
- Keep it simple stupid. Documentation should be brief and to the point. Do your best in having economy of words, don’t spend them easily. Simple bulletpoints goes a far way! Use simple langugage and short sentences.
- Use English when writing! Even if you are an entirely non-English shop, write in English still. You never know when you are going to expand into neighbouring countries that may require you to share information in English. Also, I am sure you’ve had to work with a consultant one-time or another, where the consultant is only English speaking. And no, Google Translate won’t cut it.
- Screenshots or video are not a preferred way to document. They can compliment existing documentation, but should not be your only documentation.
- Don’t create documentation using only copy/paste from whitepapers or the like. Only do this if it is a 100% fit for purpose. Instead consider linking and referencing the material rather than copy it.
- Capture the essence of the information you are creating. Make it as simple as possible to read and understand the documentation. “Economy of Words” gets you a long way!
- Don’t include passwords in the documentation. Sensitive information is usually OK as the documentation should be behind access restrictions, however passwords are not. Passwords should be changed regulary, so instead of storing them in e.g. the wiki, store them in a password manager. I’ve written a blog about using password managers here.
- Documentation should be a part of business requirements. Don’t let systems, services or other things go live without having at least a simple documentation readily available. It shouldn’t take long to set up some simple documentation scaffolding and adding some information to it.
- Keep the documentation platform highly available, good performance and ease of use. A wiki, i.e. Mediawiki, is excellent for this. If you make documentation tedious and hard, it won’t be used. Trust me on this!
- Knowledge is power; hence many will avoid documenting to keep them valuable to the business. Don’t be this guy! First of all, you will quickly be noticed using this strategy, second, any thriving business will be looking to keep good employees. Documenting, and thus helping build a healthy organisation, will ensure you are sticking around for the end game.
- Don’t get stuck doing the same repeatable tasks over and over again. Create good procedures and next time, someone else might be doing your tasks. Spreading the knowledge will allow you to move on to more challenging tasks. Having solid documents may even allow you to easily out-source your work load to the servicedesk.
- Keep your documentation solution always ready. If it’s a notepad or a wiki, always have it signed in and ready for you to type in. The moment it is not trivial to document, you are most likely going to skip it. Make it as easy as possible for yourself to create notes.
- Do not wait until the last minute to write documentation. You will forget what you did! Instead, write it as you work. If you did something wrong with your setup, requiring you to redo parts of the documentation, that is fine. Just go back and edit the step which you had to change.
- Update the documentation, don’t let it go stale. Stale documentation is bad, and wrong documentation is even worse. Ensure that it is simple and easy to update documents.
- Not everyone is an author. However, you still need to write something. Just remember to keep your information easily readable and understandable. Point back to point 1, KISS.
- Avoid repetition. Duplicate information is a no-go. It is a hassle to update information multiple places, instead use your documention platforms features for inclusion of duplicate information from one master source.
Got some tips of your own? Leave it in the comments. Thanks for reading!