When it comes to creating documentation, you must carefully pick the topic you are documenting and make sure that the topic cannot be broken down into smaller pieces. For example: if you are documenting step-by-step how an open-heart surgery is performed, most probably you will have to break this topic down into smaller pieces in order to make that the person that will use this documentation will have some background in other issues that might come up during the surgery. But, if you are documenting how to prepare scrambled eggs, you don’t have to analyze which came first: the chicken or the egg?
I am using these two examples to emphasize that there is not a single guide for preparing documentation, but you should decide on the method you are about to use case-by-case.
The second important thing to have in mind here is the medium used to store your documentation. Is your documentation plain text or video (or both)? In the case of text: do you want it publically available on your website, are you looking for an easy-to-use private platform? In the case of video: are publishing it on YouTube, are you storing it in a private cloud? Again, there is no answer to any of the questions risen above. It depends on your use case and the receivers of that documentation. But, if there is a piece of advice I can give about video documentation: don’t do it if you are using a very poor quality camera! A video prepared with poor quality camera in combination with very low internet bandwidth will make the video practically impossible to watch.
The reason we create documentation is to make sure that people will be able to find answers for any issues or problems they are facing and want to resolve. This being the case, you should always create it while putting yourself into the receivers’ shoes. Knowing who is the audience will help you use the proper tone of voice and vocabulary. A few examples:
Besides using the proper vocabulary, another reason why oftentimes documentation is not effective is because it is not well organized. Before you start writing (or filming) I would highly recommend spending some time organizing your thoughts and prioritizing different sections.
A “great documentation” besides that is easy to write should also be easy to maintain and update. Storing documentation as PDF files is a horrible example of maintenance because it is not easy to update frequently. The same goes for plain text documents, they are difficult to keep track of changes over time and can easily be “corrupted” either on purpose or accidentally by changing the content. The best approach is a platform that has “Edit” and “Save” buttons in order to make sure that unwanted edits are minimized. On a later blogpost I will share some suggestions that I have for such platforms.
Those who know me personally, know that I am not the most patient person on Earth, but I am always willing to try and figure out myself how to solve a problem before going to somebody that most probably will have a solution. In the beginning of 2021 I bought myself a new laptop and because it came with Windows 10 pre-installed I wanted to install and run Fedora on it. Soon I realized that this is not going to be easy because many BIOS configurations were either locked or disabled. Long story short, I spent an entire working day wandering around forums and docs pages trying to find a solution. I was avoiding YouTube videos on purpose because … I don’t have the patience to watch them! Anyways, I solved my problem the next morning by watching a 2 minutes video during my first 10 minutes at the office.
And because I have spent many hours of my life trying to understand documentation, I came up with the thoughts above.