technical-writing

Order sections broad-to-narrow: name, one-liner differentiator, usage, API, installation, license. The first screen must let a stranger answer whether this is what they need, and anything over four sections gets a table of contents with machine-checked anchors.

A tutorial is a lesson in a controlled setting with one managed path and explicit basics, aimed at learners. A how-to serves competent users at work, branches with conditions, and assumes familiarity. Mixing them on one page is the most common documentation failure.

Put enumerable facts like options, flags, and exit codes in tables rather than prose, state preconditions and postconditions per operation, and give exact copy-pasteable strings for commands and config. Good agent docs converge with good human docs.

Ship it for developer-tool docs since IDE agents and MCP servers do fetch it, but generate it at build time rather than hand-authoring. Skip it as an SEO tactic since major search crawlers ignore it, and publish llms-full.txt alongside the index.

Execute every runnable example in CI using doc-tests, doctest, or extracted README snippets, and verify flags and commands against the actual source before shipping. Update documentation in the same commit as the behavior change it describes.

Minimalism fits how-to guides where competent users fill gaps, but tutorials must stay explicit about basics since the teacher owns the outcome. It is documentation designed around action, not an excuse to write less documentation overall.