* Glossary for any special terminology that can't just be googled - especially project specific terminology that may be confusing, and double especially terms or phrases which are used slightly differently to the way everybody else uses them (e.g. 'user' means something slightly different almost everywhere).
* Lots of "why" describing why the software behaves in ways that seem surprising at first glance.
Even less arguable is when examples that worked are broken by an update and remain unchanged--they'll work for people on outdated versions but break when they upgrade, and also break for new users, and nothing will sufficiently explain why.
Please add your documentation examples to your testing pipeline (or write tests clearly enough that they can be good examples, and just use those).
The same YAML files that are used to regression test the software are used to generate markdown docs for the website.
This seems like a pretty good practice to me. Are there any good testing libraries for keeping your documentation examples tested and up to date?
On my most recent project I split the docs in two; a 'guide' with example code and output - it has more of an 'overview' feel. The other half is the technical (API) docs built from comments in the source code.
It's not the most exciting project in the world, but it's a Rails form builder that meets GOV.UK requirements. Here's a draft of the guide if anyone's interested.
It's generated via Nanoc which loads the form builder and uses it to generate the example input, rendered output and HTML - in theory it can't be out of date or broken.