How do I write technical docs people actually finish?
The first reader is not your manager. It is the colleague who has to follow this document in three months. Decide what they need to do with it.
How to do it
Turn scattered notes into a usable outline
Paste your notes, meeting records, and links into 'Turn scattered notes into structure'. Ask for a one-sentence thesis, three to five sections with the question each one answers, every fragment placed, and any two ideas that duplicate or contradict each other. Confirm the outline before drafting; it saves whole paragraphs of rework.
Let headings show the reader what matters
Give the draft to 'Add subheadings that reveal the structure'. It should mark where the topic actually changes rather than cutting every few paragraphs, then keep each heading to four to eight words, written as a statement, so the heading alone says what the section answers. Sections with no nameable topic should be merged or cut, and it should list what it added or changed.
Check every claim against its evidence
Give the judgment-bearing paragraphs to 'Check whether claims match their evidence'. It separates fact, trend, causation, and prediction, labels the evidence type, and flags a single case used to support 'all' or correlation presented as cause. For each mismatch, ask for a weaker wording or the evidence it needs; do not let it rewrite the prose.
Rewrite for a named reader
Name the reader (product, customer, or leadership) and give the technical sections to 'Rewrite technical docs for non-technical readers'. The opening sentence should say what this means for that reader. Explain each term on first use with everyday experience, keep limits, failure modes, and numbers, and list ambiguities separately as 'needs confirmation'. Do not replace a mechanism with a metaphor.
Test it on an impatient reader
Finally, use 'Play the reader who will close the tab' with a specific reader identity. Ask where they would stop reading, which sentence lost them, which three passages talk past the reader, which argument the author has not thought through, and which half to cut. Cut according to the answers instead of adding more.
Prompts used
FAQ
How long should a technical doc be?
It depends on the decision the reader has to make with it. Being able to stop at the right place and find the answer matters more than length. Step 5 usually shows that the paragraphs you cut were ones the reader would have skipped.
Should I use AI to draw the architecture diagram?
You can, but fix the structure and headings in steps 1 and 2 first. Otherwise the diagram inherits the mess in the draft. Every arrow in it should correspond to a mechanism described in the text.
For non-technical readers, should I remove the risks?
No. Step 4 asks you to keep limits, failure modes, and numbers, and only translate implementation details into consequences the reader can recognize. A doc that removes risk loses trust precisely when something goes wrong.