A couple of thoughts on technical documentation.
(By "documentation" I mean everything except the source code. Blog posts, API documentation, specifications, code comments, pull request descriptions, commit messages, code review comments, ticket descriptions and comments, videos, pictures, diagrams, presentations etc. etc.)
-
The best documentation is no documentation. For example, prefer refactoring the code to make it self-explanatory if it allows removing the source code comment.
-
By default assume nobody reads documentation. Extra effort is needed to make documentation easy to find and engaging enough so that people would want to read it.
-
Prefer stories to dry descriptions. We are hard-wired to absorb account of events. For example, "I did this, and that, then this happened, and I did this in response". (Also see the previous point.)
-
Prefer the "why" documentation rather than "how" documentation. The "how" can be revealed while observing the system (behaviour, source code, logs, commit messages, configuration) and it never becomes out-of-date. On the other hand, the "why" is often implicit.
-
The best documentation writer is often the person who is new to the sytem. For example, consider "how to configure local development environment" guide. This guide is better written by a new person who tries to configure the environment on her machine and writes notes as she goes. It's harder to do when the author is deep in the system and no longer remembers how was it in the beginning.
-
Prefer documenting "public" surface of the system rather than internals. For example, the external APIs.
-
Prefer documenting data structures rather than code. The classic "Show me your flowcharts and conceal your tables, and I shall continue to be mystified. Show me your tables, and I won’t usually need your flowcharts; they’ll be obvious." (Fred Brooks).