Currently, numerous beautiful standards, frameworks and computer languages exist that we all love to use or which we may be required to use.
Unfortunately, with the advent of online documentation, documentation authors more and more seem to lose their sense of providing information in a conclusive and informative yet concise manner.
At the time of writing this Gist, the Angular documentation alone takes almost 1,200 printed pages to read. Webpack documentation is equally monstrous: It takes almost 800 pages!
Another example of rampant documentation is the Microsoft ASP.NET Core documentation: It, too, takes more than 1,200 printed pages that Microsoft expects to be read by programmers in order to thoroughly understand and program all aspects of ASP.NET Core:
Moreover, reading the Microsoft ASP.NET Core documentation unveils that it is a big pile of randomly assembled information – ragged, unfocussed and non-edible.
That's an unbearable situation. Learning standards, frameworks and computer languages has become an unachievable, Sisyphean task.
We all know how important it is to have a sound knowledge of all aspects of a standard, framework or computer language in order not to run into security issues or not to suffer from accidental loss of data just due to the fact that programmers didn't know any peculiarity of a standard, framework or computer language they chose for their project.
Nowadays, new standards arise and frameworks get launched or accrue almost every month.
It's time now for authors of standards, frameworks and computer languages to adjust their documentation intent:
- Do you just want to show off or do you want the world to be able to fully comprehend and utilize your product?
- Remember that your readers – in contrast to you – will not be using your product or even focus on your technology stack every day. They may not be aware of the latest state of information. So, write your documentation for occasional users.
- Separate concerns when writing your documentation. Be focussed, complete and concluded in each chapter of your documentation.
- Be concise and precise. Folks must read dozens of documentation chunks like yours. Your standard, framework or computer language is only one single step on a long stairway to success. By keeping your manual concise you're also keeping it manageable. If you cannot describe in less than 500 printed pages how to handle your product comprehensively, your work may be much less of a blessing to mankind than you believe it is.
- Keep all of your documentation updated. Delete any obsolete information that's not applying to the latest version.
- Let your documentation be coherent and self-contained. Working with your product should neither be a matter of try-and-error nor the hassle of hide-and-seek. Don't expect readers to go hunting on other websites for relevant information about your product. Your product and documentation should have a 1:1 relationship. This is your debt.
- Write in a friendly and colloquial tone that's easy to follow.
- Have foreign readers in mind when choosing your words.
- Rewrite your documentation to be comprehensive, yet concise and easy to grasp.
- Don't intermingle different aspects into a single chapter.
- Keep the amount of your documentation below 500 printed pages.
A documentation not adhering to all the above suggestions is of no help to anyone. It's just an unnecessary moloch, wasting people's time and keeping them repeatedly ask "stupid" questions in technical forums.