documentation-expert

Documentation Expert Skill

Overview

This skill guides the authoring, structuring, and automated validation of Zero-Fluff technical documentation, root AGENTS.md guides, official Google DESIGN.md references, and Mermaid.js architectural diagrams. Applying the Diátaxis framework (Tutorials, How-To Guides, Reference, Explanation), it enforces strict line budgets, portable relative links, and zero-boilerplate clarity.

When to Use

Trigger Scenarios

• Authoring or auditing READMEs, runbooks, API references, and root AGENTS.md (<= 90 lines).
• Ensuring documentation aligns with official Google 2-layer DESIGN.md (<= 110 lines) and docs/<feature-name>/ line caps.
• Modeling architectures, sequence flows, or schemas with syntax-safe Mermaid.js diagrams.
• Validating markdown heading hierarchy, relative links, and path portability.

When NOT to Use

• Authoring MADR architectural decisions (adr-NNN-*.md): Route to senior-architect-engineering.
• Authoring UI token systems (DESIGN.md): Route to ui-ux-designer.
• Automated codebase cartography (project-context.md): Route to repo-research.

Process

Phase 1: Diátaxis Pillar & Zero-Fluff Budget Alignment

1. Select one Diátaxis mode per section — never mix tutorials, how-to steps, reference tables, and explanations together.
2. Enforce strict Zero-Fluff conciseness caps across project and feature artifacts:
   • Root AGENTS.md <= 90 lines (verified build/lint/test commands, conventions, links to DESIGN.md & context/memory/MEMORY.md).
   • Root Google DESIGN.md <= 110 lines (YAML tokens + 8 sections) and feature UI delta in docs/<feature-name>/spec.md (## Design <= 30 lines).
   • Feature specs in docs/<feature-name>/: single spec.md (## Product <= 50, ## Design <= 30, ## Architecture <= 50), adr-NNN-*.md <= 55 lines, test-matrix.md <= 80 lines; verification reports are returned in the reviewer's final message (<= 50 lines), never written as files.