Documentation
Technical writing, diagram-as-code, and documentation lifecycle management. Treats docs as code: version-controlled, linted, and CI-verified.
When to use: Creating or updating technical documentation, generating Mermaid diagrams (flowcharts, ERDs, sequence diagrams), auditing documentation coverage against code, or establishing style guides.
When NOT to use: Writing marketing copy, blog posts, or content that does not live alongside code.
Quick Reference
| Task |
Approach |
Key Point |
| Doc sync audit |
git diff main...HEAD + export scan |
Compare symbols against doc coverage |
| Sequence diagram |
Mermaid sequenceDiagram + autonumber |
Map messages to function calls |
| ERD |
Mermaid erDiagram + Crow's Foot |
Derive from Drizzle/Prisma schemas |
| Gitgraph |
Mermaid gitGraph |
Standardize on main/develop/feature branches |
| Feature release doc |
Overview + Config + Examples + Troubleshooting |
Checklist for every new feature |
| API reference |
Generate from JSDoc/TSDoc annotations |
Never write API refs manually |
| Style guide |
Active voice + present tense + direct address |
Conversational but precise |
| AI-assisted drafting |
Inventory + gap analysis + draft + human review |
AI drafts, humans verify accuracy |
| Markdown standard |
YAML frontmatter + language-tagged code blocks |
Always specify code block language |
| Complex diagrams |
Split into focused sub-diagrams + subgraphs |
Limit to 15-20 nodes per diagram |
| README template |
Badges + description + quick start + API link |
First thing users see; keep under 200 lines |
| ADR format |
Status, context, decision, consequences |
Numbered, immutable once accepted |
| Runbook |
Symptoms, diagnosis, resolution, escalation |
Written for 3 AM incidents; no ambiguity |
Common Mistakes
| Mistake |
Correct Pattern |
| Using static images for technical diagrams |
Write Mermaid syntax inline in Markdown |
Generic participant names like Agent1 |
Use specific service or role names matching the architecture |
| Manually writing API reference docs |
Generate from JSDoc/TSDoc annotations in source code |
| Diagrams with 20+ nodes and no grouping |
Use subgraphs to group related nodes; limit to 15-20 |
| Documentation referencing outdated defaults |
Run doc sync audit comparing exports against coverage |
| Using "Click here" link text |
Use descriptive anchor text for accessibility and clarity |
| Skipping heading hierarchy levels |
Never go from H2 to H4; keep hierarchy sequential |
| Mixing wall-of-text paragraphs |
Use bullet points, tables, and diagrams for scannability |
| No ADRs for architectural decisions |
Record decisions with context, status lifecycle, and consequences |
Delegation
- Scan codebase for undocumented exports and documentation gaps: Use
Explore agent
- Generate a full documentation site with diagrams from an existing codebase: Use
Task agent
- Plan documentation architecture and information hierarchy for a new project: Use
Plan agent
If the mermaid-diagrams skill is available, delegate complex diagram creation and advanced Mermaid syntax questions to it.
Otherwise, recommend: npx skills add oakoss/agent-skills --skill mermaid-diagrams
If the tldr-expert skill is available, delegate summary and brief generation to it.
References
- Writing Style -- Voice, tone, formatting rules, error message guidelines, and structural standards
- Mermaid Diagrams -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting
- Doc Coverage -- Feature inventory, gap analysis, code-first and doc-first audit workflows
- AI Collaboration -- AI-human doc workflow, hallucination handling, documentation-as-code practices
- Markdown Standards -- Frontmatter, headings, code blocks, tables, callouts, and link conventions
- Runbooks and Onboarding -- Incident runbook templates, escalation paths, and developer onboarding guides
1---2name: technical-docs3description: Technical documentation writing and diagram generation. Use when creating docs, syncing documentation with code changes, building Mermaid diagrams, running doc coverage audits, or establishing writing style guides. Use for doc-as-code workflows, ERD generation, sequence diagrams, documentation gap analysis, and AI-assisted drafting.4license: MIT5---6
7# Documentation
8
9Technical writing, diagram-as-code, and documentation lifecycle management. Treats docs as code: version-controlled, linted, and CI-verified.
10
11**When to use**: Creating or updating technical documentation, generating Mermaid diagrams (flowcharts, ERDs, sequence diagrams), auditing documentation coverage against code, or establishing style guides.
12
13**When NOT to use**: Writing marketing copy, blog posts, or content that does not live alongside code.
14
15## Quick Reference
16
17| Task | Approach | Key Point |
18| -------------------- | ----------------------------------------------- | -------------------------------------------- |
19| Doc sync audit | `git diff main...HEAD` + export scan | Compare symbols against doc coverage |
20| Sequence diagram | Mermaid `sequenceDiagram` + `autonumber` | Map messages to function calls |
21| ERD | Mermaid `erDiagram` + Crow's Foot | Derive from Drizzle/Prisma schemas |
22| Gitgraph | Mermaid `gitGraph` | Standardize on main/develop/feature branches |
23| Feature release doc | Overview + Config + Examples + Troubleshooting | Checklist for every new feature |
24| API reference | Generate from JSDoc/TSDoc annotations | Never write API refs manually |
25| Style guide | Active voice + present tense + direct address | Conversational but precise |
26| AI-assisted drafting | Inventory + gap analysis + draft + human review | AI drafts, humans verify accuracy |
27| Markdown standard | YAML frontmatter + language-tagged code blocks | Always specify code block language |
28| Complex diagrams | Split into focused sub-diagrams + subgraphs | Limit to 15-20 nodes per diagram |
29| README template | Badges + description + quick start + API link | First thing users see; keep under 200 lines |
30| ADR format | Status, context, decision, consequences | Numbered, immutable once accepted |
31| Runbook | Symptoms, diagnosis, resolution, escalation | Written for 3 AM incidents; no ambiguity |
32
33## Common Mistakes
34
35| Mistake | Correct Pattern |
36| ------------------------------------------- | ----------------------------------------------------------------- |
37| Using static images for technical diagrams | Write Mermaid syntax inline in Markdown |
38| Generic participant names like `Agent1` | Use specific service or role names matching the architecture |
39| Manually writing API reference docs | Generate from JSDoc/TSDoc annotations in source code |
40| Diagrams with 20+ nodes and no grouping | Use subgraphs to group related nodes; limit to 15-20 |
41| Documentation referencing outdated defaults | Run doc sync audit comparing exports against coverage |
42| Using "Click here" link text | Use descriptive anchor text for accessibility and clarity |
43| Skipping heading hierarchy levels | Never go from H2 to H4; keep hierarchy sequential |
44| Mixing wall-of-text paragraphs | Use bullet points, tables, and diagrams for scannability |
45| No ADRs for architectural decisions | Record decisions with context, status lifecycle, and consequences |
46
47## Delegation
48
49- **Scan codebase for undocumented exports and documentation gaps**: Use `Explore` agent
50- **Generate a full documentation site with diagrams from an existing codebase**: Use `Task` agent
51- **Plan documentation architecture and information hierarchy for a new project**: Use `Plan` agent
52
53> If the `mermaid-diagrams` skill is available, delegate complex diagram creation and advanced Mermaid syntax questions to it.
54> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill mermaid-diagrams`
55> If the `tldr-expert` skill is available, delegate summary and brief generation to it.
56
57## References
58
59- [Writing Style](references/writing-style.md) -- Voice, tone, formatting rules, error message guidelines, and structural standards
60- [Mermaid Diagrams](references/mermaid-diagrams.md) -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting
61- [Doc Coverage](references/doc-coverage.md) -- Feature inventory, gap analysis, code-first and doc-first audit workflows
62- [AI Collaboration](references/ai-collaboration.md) -- AI-human doc workflow, hallucination handling, documentation-as-code practices
63- [Markdown Standards](references/markdown-standards.md) -- Frontmatter, headings, code blocks, tables, callouts, and link conventions
64- [Runbooks and Onboarding](references/runbooks-and-onboarding.md) -- Incident runbook templates, escalation paths, and developer onboarding guides
oakoss