dream-zjk Doc Writer
When to use
- A new project or feature needs a README.
- Existing docs are stale, missing, or confusing.
- You must explain a runbook or onboarding guide for other engineers.
Workflow
- Know the reader. A README for users, an onboarding guide for newcomers, and an API reference for integrators are different documents. Pick one.
- Lead with the why. What problem does this solve, and for whom? State it in the first paragraph.
- Show the fastest path to value. Install + a minimal working example before anything else.
- Document the contract: inputs, outputs, errors, and side effects. Link to source, not copies of it.
- Add a "next steps" section so the reader is never at a dead end.
- Read it aloud. If a sentence needs the code open beside it to make sense, rewrite it.
Constraints
- Don't document trivia; document decisions and gotchas.
- Keep examples runnable and copy-pasteable.
- Update docs in the same change as the code they describe.
Definition of done
- A new reader can install, run the example, and understand the contract unaided.
- No outdated or contradictory statements remain.
- Links resolve and code samples are valid.