# Technical Docs

> 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. Use when this capability is needed.

- Skill: `tomevault-io/technical-docs` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/technical-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/technical-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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             |

## 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     |

## 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: `pnpm dlx skills add oakoss/agent-skills -s mermaid-diagrams -a claude-code -y`

## References

- [Writing Style](references/writing-style.md) -- Voice, tone, formatting rules, error message guidelines, and structural standards
- [Mermaid Diagrams](references/mermaid-diagrams.md) -- Sequence, ERD, gitgraph, flowchart patterns with anti-patterns and troubleshooting
- [Doc Coverage](references/doc-coverage.md) -- Feature inventory, gap analysis, code-first and doc-first audit workflows
- [AI Collaboration](references/ai-collaboration.md) -- AI-human doc workflow, hallucination handling, documentation-as-code practices
- [Markdown Standards](references/markdown-standards.md) -- Frontmatter, headings, code blocks, tables, callouts, and link conventions

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/jbabin91) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->