Documentation

Documentation tooling is judged by one property: whether the documentation stays true. Everything else — search, theming, versioning, navigation — is in service of that, because documentation that is wrong is worse than none, since a reader trusts it and then loses an hour.

The strongest structural answer is keeping documentation next to the code, in the repository, reviewed in the same pull request as the change. This makes the documentation update part of the work rather than a follow-up task that never happens, and it means a reviewer sees both. Tools built around this — static generators that build from files in the repo — have a durable advantage over hosted editors, at the cost of being harder for non-engineers to contribute to.

The second answer is generating whatever can be generated. API references, configuration options, command-line flags and schema documentation should be produced from the source of truth rather than written alongside it. Anything written by hand that describes something machine-readable will drift.

What cannot be generated is the part that matters most: why something exists, how the pieces fit, what you should do first, and what to do when it goes wrong. Documentation that is complete on the reference axis and empty on the explanatory one is the most common failure in the category, and it is why so many well-documented projects are hard to start with.

The single highest-value page in most documentation is a working quickstart that takes a reader from nothing to something running, with no branches. Every decision it asks the reader to make is a place they stop. Test it by handing it to someone who has not used the tool and watching without helping.

Search quality determines whether large documentation is usable at all, and it is where hosted tools earn their money. Beyond a few hundred pages, navigation stops being how anyone finds anything.

Versioning matters as soon as you have users on more than one release, and it is much easier to set up before you need it than after. Tools that handle this natively save an eventual restructuring.

Examples are worth more than prose, and complete runnable examples are worth more than fragments. A reader will copy the example; make sure it works.