Technical Documentation
For writing style, tone, and voice guidance, use Skill(ce:writer) with The Engineer persona.
Core Principles
- 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.
- 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:
- 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