technical-docs

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