Technical Documentation

For writing style, tone, and voice guidance, use Skill(ce:writer) with The Engineer persona.

Core Principles

1. Progressive Disclosure

Reveal information in layers:

Layer Content User Question

1 One-sentence description What is it?

2 Quick start code block How do I use it?

3 Full API reference What are my options?

4 Architecture deep dive How does it work?

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

2. Task-Oriented Writing

<!-- Bad: Feature-oriented -->

AuthService Class

The AuthService class provides authentication methods...

<!-- Good: Task-oriented -->

Authenticating Users

To authenticate a user, call login() with credentials:

3. Show, Don't Tell

Every concept needs a concrete example.

Formatting 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

Problem Fix

Wall of text Break up with headings, bullets, code, tables

Buried critical info Warnings/breaking changes at TOP

Missing error docs Always document what can go wrong

Templates

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

Related Skills

• Skill(ce:writer)

• Writing style, tone, and voice (load The Engineer persona)

• Skill(ce:visualizing-with-mermaid)

• Architecture and flow diagrams