---

name: documenting-systems description: Creates task-oriented technical documentation with progressive disclosure. Use when writing READMEs, API docs, architecture docs, or markdown documentation.

Technical Documentation

Core Principles

1. Progressive Disclosure

Reveal information in layers:

Warnings, breaking changes, and prerequisites go at the TOP.

2. Task-Oriented Writing

Copy<!-- ❌ Feature-oriented -->
## AuthService Class
The AuthService class provides authentication methods...

<!-- ✅ Task-oriented -->
## Authenticating Users
To authenticate a user, call login() with credentials:

3. Show, Don't Tell

Every concept needs a concrete example.

Writing Standards

• Sentence case headings: "Getting started" not "Getting Started"
• Max 3 heading levels: Deeper means split the doc
• Always specify language in code blocks
• Relative paths for internal links
• Tables for structured data with 3+ attributes

Quality Checklist

• Code examples tested and runnable
• No placeholder text or TODOs
• Matches actual code behavior
• Scannable without reading everything
• Reader knows what to do next

Anti-Patterns

Templates

For README, API endpoint, and file organization templates, see references/templates.md.

Diagrams

Use Skill(ce:visualizing-with-mermaid) for architecture and flow diagrams.