Documentation

Documentation Generation Skill

When creating or improving documentation, follow these guidelines:

When to Activate

• User requests /docs or /documentation
• Creating README, CHANGELOG, CONTRIBUTING files
• Writing architecture documentation
• API documentation requests
• Any technical documentation needs

Core Principles

1. Treat documentation as code - Version control, review, CI/CD
2. Follow Diataxis framework - Tutorials, How-tos, Reference, Explanation
3. Write for humans - Clear, concise, actionable
4. Include diagrams - ASCII for CLI/Git, Mermaid for web
5. Use standard formats - CommonMark/GFM Markdown

File Naming Conventions

ASCII Diagrams

• Use box-drawing: ┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼
• Heavy boxes: ┏ ━ ┓ ┃ ┗ ┛ ┣ ┫ ┳ ┻ ╋
• Double boxes: ╔ ═ ╗ ║ ╚ ╝ ╠ ╣ ╦ ╩ ╬
• Arrows: → ← ↑ ↓ ↔ ▶ ◀ ▲ ▼ ──▶ ◀──
• Max width: 80-85 characters for terminal compatibility
• Always include legends for complex diagrams

Diagram Types

• Flowcharts: Decision diamonds, process boxes
• Architecture: Three-tier, microservices layouts
• Sequence: Vertical lifelines with arrows
• ERD: Tables with PK/FK notation
• State machines: States with transitions

Document Structure

1. Title with ASCII banner (for major docs)
2. Table of Contents
3. Visual diagram first (architecture overview)
4. Detailed explanation after
5. Code examples (copy-paste friendly)
6. References/links at end

Quality Checklist

• Can a new developer get started in under 10 minutes?
• Is the documentation structure intuitive?
• Are code examples copy-paste friendly?
• Is the documentation up to date with the code?
• Are diagrams version-controlled as code?

References

See ASCII_DIAGRAMS.md for comprehensive diagram examples. See TEMPLATES.md for document templates.

Industry Standards Followed

• Google Developer Documentation Style Guide
• Microsoft Writing Style Guide
• Diataxis Documentation Framework
• Keep a Changelog (v1.1.0)
• Semantic Versioning (v2.0.0)
• ADR (Architecture Decision Records)