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 APIproduces 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 |
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.