Technical Writing skill for Codex

A technical document is done when the intended reader can act on it without asking the author a question, every factual claim matches the system as it is today, and a reader who stops after the first screen still leaves with the main point.

Before writing anything

Answer these four questions in a scratch note. If any answer is “not sure”, ask the user or read more source material before drafting.

Question	Why it matters
Who is the reader, concretely? (“backend engineer new to billing”, not “developers”)	Sets vocabulary, assumed knowledge and depth
What must they do or decide after reading?	Becomes the first paragraph and the structure
What do they already know?	Everything below that line needs a sentence or a link
Where will they read it? (PR, wiki, docs site, printed for a review)	Sets length, format and link style

Then gather facts from the source of truth, not from memory:

• Read AGENTS.md and any docs/ style notes for house conventions (spelling, heading case, product names).
• Read the code paths, configs and tests the document describes. rg -n "<term>" to find where a concept actually lives.
• Run the commands you will quote. A command you have not run is a guess.
• Note version numbers and dates; technical prose goes stale and the reader needs to know “as of when”.

Pick the document shape

Reader needs to…	Shape	Opens with
Decide between options	Decision doc	The recommendation and the one-line reason
Understand how a system works	Explainer	A one-paragraph model of the system, then a diagram
Change a system safely	Design doc	Problem, constraints, proposal; alternatives later
Move from old to new	Migration guide	Who is affected, the deadline, the steps
Look something up	Reference	A table or list; no narrative
Learn a skill by doing	Tutorial	What they will build; hand off to tutorial-writing

If the user’s material mixes shapes (a design doc that is half tutorial), split it and link the parts. Mixed documents serve no reader well; see $diataxis-docs for the full classification.

Workflow

- [ ] 1. Write the reader, the goal and the one-sentence takeaway at the top of a scratch file
- [ ] 2. Gather facts from code, configs and commands; record versions
- [ ] 3. Outline as headings that are statements or questions, not single nouns
- [ ] 4. Draft the first paragraph last-but-one: it must carry the takeaway alone
- [ ] 5. Draft sections; one idea per paragraph, topic sentence first
- [ ] 6. Add examples, a diagram if the system has more than three moving parts
- [ ] 7. Run the revision passes below
- [ ] 8. Verify every command, path, name and number against the source

Outline rules

• Headings that say something beat headings that label something: “Writes are retried three times, then dead-lettered” over “Retries”.
• Order by what the reader needs first, not by the order things were built or discovered.
• Put background, history and rejected alternatives after the proposal, or in an appendix.
• Keep nesting to three heading levels. A fourth level means the section wants to be its own page.

Sentence and paragraph rules

• Conclusion first. Every section opens with its point; detail follows. Readers skim the first sentence of each paragraph.
• One term per concept. Pick “workspace” or “project”, define it on first use, then never switch. Synonyms read as different things to a technical reader.
• Concrete over abstract. “The job retries after 1 s, 4 s and 16 s” over “the job uses exponential backoff with sensible defaults”.
• Name the actor. “The scheduler deletes expired rows” over “expired rows are deleted”. Passive voice is fine when the actor genuinely does not matter.
• Quantify. Replace “fast”, “large”, “soon”, “a few” with numbers or ranges.
• Lists for parallel items, prose for reasoning. Bullets cannot carry “because” and “therefore”; arguments belong in sentences.
• Short paragraphs. Three to five sentences. A paragraph that covers two ideas splits.
• Hedge once, precisely. “Untested on Windows” beats sprinkling “should”, “may” and “generally” across every sentence.

Examples, code and diagrams

• Every abstract rule gets one concrete example within the same screen.
• Code blocks carry a language tag, are copy-pasteable, and use realistic values (order_id=8812, not foo). Mark placeholders consistently: <project-id>.
• Show output when the reader needs to recognise success: put expected output in its own block, labelled.
• Use a diagram for flows with more than three components or any sequence across services. Mermaid in Markdown keeps it versioned:

sequenceDiagram
    Client->>API: POST /orders
    API->>Queue: enqueue charge
    Queue->>Worker: deliver (at-least-once)
    Worker->>Stripe: create PaymentIntent

• Label diagram arrows with what moves (a request, an event, a file), not with “calls”.

Revision passes

Do separate passes; each one looks for a single kind of problem.

Pass	Look for	Fix
Takeaway	Can the first paragraph stand alone?	Rewrite it as the answer to “so what?”
Structure	Sections out of the reader’s order	Reorder; move history and alternatives down
Terminology	Same concept, two names; undefined acronyms	Pick one; define on first use
Precision	Vague words: some, many, fast, soon, etc.	Replace with numbers, names, ranges
Length	Throat-clearing intros, repeated summaries	Delete; one summary at most
Accuracy	Commands, paths, flags, version numbers	Re-run and re-read the source

For line-level tightening use $copy-editing; for non-specialist audiences use $plain-language.

Gotchas

• Writing from the author’s mental model: the order you discovered things is rarely the order a reader needs them.
• “Simply”, “just”, “obviously” and “easy” insult readers who are stuck. Delete them.
• Screenshots of terminals or code cannot be searched, copied or diffed. Use text.
• Relative time (“recently”, “the new API”) rots. Use dates and version numbers.
• Documenting intended behaviour instead of actual behaviour. When code and spec disagree, say so explicitly and flag it to the user rather than picking one silently.
• Burying a breaking change or a required action in paragraph six. Required actions go first, in a callout.

Verification

• Hand the first paragraph alone to a reviewer (or reread it cold): can they state the takeaway and the action?
• Every command in the document was executed in this session, or is explicitly marked as not run with the reason (needs production access, needs network).
• rg every identifier, flag and config key in the doc against the repo; zero misses.
• Links resolve (lychee --offline docs/ for local links when lychee is installed).
• If a check fails, fix the document, not the reader’s expectations: rewrite the sentence that misled.

Output contract

When delivering a document, report alongside it:

**Reader:** platform engineers onboarding to the ingest pipeline
**Goal:** they can trace a failed event to its dead-letter record and replay it
**Takeaway (first paragraph):** Events retry 3 times over ~21 s, then land in `ingest_dlq`; replay with `make replay ID=...`.
**Verified:** all 6 commands run against local stack; config keys checked in `ingest/config.py`
**Not verified:** production alert names (no access); marked in the doc
**Open questions for the author:** whether the 7-day DLQ retention is policy or default