Writing docs developers actually read
Documentation is a product surface. Treat it like copywriting: know the reader, know the job, remove everything else.
A developer opens your documentation in a hostile state: something is broken, or a deadline is close. They are scanning, not reading.
That means the first screen must answer the question they arrived with. Put the working example above the conceptual overview. Concepts are for the second visit.
Write the failure modes down. The paragraph that says 'if you see this error, it means X' saves more support hours than any tutorial.
And use the words your users use, not the words your codebase uses. Internal naming is a private joke your customers were not part of.
Working on something like this?
I take on a small number of automation, development and writing engagements each quarter.
Get in touch