# Documentation

> Generate professional technical documentation with ASCII diagrams, flowcharts, architecture visualizations, and industry-standard templates

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

| Location | Convention | Example |
|----------|------------|---------|
| Root level | UPPERCASE | `README.md`, `CHANGELOG.md` |
| docs/ folder | lowercase kebab-case | `getting-started.md` |
| ADRs | numbered | `0001-use-typescript.md` |

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