Table of Contents
Quick Answer
AI writes strong first drafts of ADRs, RFCs, runbooks, and architecture docs when you provide structure (via templates), context (code + diagrams), and audience. Always human-edit for accuracy.
- Templates beat free-form prompts every time
- AI is better at rewriting than drafting from scratch — sketch bullets first
- Runbooks must be tested by someone unfamiliar with the system
What You'll Need
- A docs home: Fumadocs, Docusaurus, MkDocs, Notion
- Templates for each doc type
- AI IDE with access to your codebase
- Review process (PR-based for docs)
Steps
- Standardize templates. ADRs (Michael Nygard format), RFCs (Rust-lang style), runbooks (SRE Google style).
- Provide context. Paste relevant code, architecture diagrams (Mermaid), and existing docs.
- Sketch bullets. Write 10 bullets covering what you want — AI expands them better than free-form.
- Generate the draft. Prompt: Using this ADR template, write an ADR for choosing pgvector over Qdrant.
- Add diagrams. Ask for Mermaid: Create a sequence diagram for this login flow.
- Human edit for accuracy. Especially numbers, dates, and decisions.
- Review with an outsider. Fresh eyes catch unclear passages.
- Version with code. Docs-as-code: MDX in Git, reviewed via PR.
Common Mistakes
- Vague prompts. Write docs for my API produces generic fluff.
- Skipping decision rationale. ADRs must explain why alternatives were rejected.
- Untested runbooks. Runbooks that haven't been exercised are fiction.
- AI-invented metrics. Always replace fabricated numbers with real ones.
Top Tools
Tool
Use
Fumadocs
MDX-based docs site
Docusaurus
Versioned docs
Mermaid
Diagrams as code
Claude Code
Repo-aware drafting
Vale
Prose linting
FAQs
What goes in an ADR? Context, decision, consequences, alternatives considered.
How long should an RFC be? 1-5 pages. Longer loses readers.
Can AI write runbooks? Yes — but test each step on a non-prod system before publishing.
Should docs live with code? Yes — /docs folder in the repo, deployed via CI.
Does AI know my team's conventions? Only if you include a style guide in the prompt.
Can AI update stale docs? Yes — diff the code, ask: Update these docs to match the new code.
Conclusion
AI lowers the activation energy for technical writing. Use templates, sketch bullets, let AI expand, human edit. Misar Blog↗ publishes free templates for ADRs, RFCs, and runbooks.