Comprehensive Technical Documentation

Creates a complete documentation suite that serves different audiences and use cases, from quick reference to deep technical analysis.

Quick Reference

User Request	Documentation Output
"写技术文档" or "Write docs"	Full 4-document suite
"解释原理" or "Explain how it works"

Technical Principles doc + Architecture | | "快速参考" or "Quick reference" | Quick Reference Guide only | | "画架构图" or "Draw architecture" | Architecture Visualization doc | | "写导航索引" or "Create index" | Navigation Index doc |

Background

When documenting complex systems, a single monolithic document fails to serve different audiences:

• - New users need quick start guides
• Architects need visual diagrams
• Developers need deep technical details
• Everyone needs navigation

This skill solves that by creating a layered documentation system with 3-4 complementary documents.

Solution

The Documentation Suite

Create these documents (adapt based on project scope):

1. 1. 📖 Technical Principles (技术原理文档.md)

- Deep dive into how the system works - Design philosophy and decisions - Implementation details - Best practices - Target: Developers, contributors - Reading time: 30-60 minutes

1. 2. 📊 Architecture Visualization (架构与流程可视化.md)

- Mermaid diagrams for architecture - Flow charts and sequence diagrams - State machines - Data flow diagrams - Target: Architects, visual learners - Reading time: 15-30 minutes

1. 3. 🔖 Quick Reference Guide (快速参考指南.md)

- Templates and examples - Command cheat sheets - Field definitions - Troubleshooting - Target: All users (most frequently used) - Reading time: 5-15 minutes

1. 4. 🗺️ Navigation Index (README-文档索引.md or 文档索引.md)

- Document comparison table - Learning paths by role - Scenario-based navigation - FAQ with document links - Target: First-time users, navigators - Reading time: 5 minutes

Step-by-Step Workflow

Phase 1: Deep Understanding (15-30 minutes)

Read core files to understand the system:

CODEBLOCK0

Decision point: If system is small (<5 files), might only need 1-2 docs.

Phase 2: Analysis & Extraction (10-15 minutes)

Extract key information:

1. 1. Core Concepts - What problem does it solve?
2. Architecture - What are the major components?
3. Data Flow - How does information move?
4. Integration Points - How does it connect to other systems?
5. User Workflows - What are the main use cases?
6. Pain Points - What commonly goes wrong?

Phase 3: Document Creation (30-60 minutes)

Create documents in this order:

1. Technical Principles (技术原理文档.md)

Structure:
CODEBLOCK1

Word count: 5000-8000 words for complex systems

2. Architecture Visualization (架构与流程可视化.md)

Include these diagram types:

CODEBLOCK2

Diagram count: 10-15 Mermaid diagrams

3. Quick Reference Guide (快速参考指南.md)

Structure:
CODEBLOCK3

Word count: 2500-3500 words

4. Navigation Index (README-文档索引.md)

Structure:
CODEBLOCK4

Word count: 2000-3000 words

Phase 4: Visualization (20-30 minutes)

Create Mermaid diagrams for Architecture doc:

Essential diagrams:

1. 1. System architecture (graph TB with subgraphs)
2. Data flow (flowchart LR)
3. Main sequence flow (sequenceDiagram)
4. Decision tree (flowchart TD)
5. State machine (stateDiagram-v2)
6. File system topology (graph TD)

Mermaid best practices:

• - Use subgraph for logical grouping
• Apply style for visual hierarchy (colors)
• Keep each diagram focused on one aspect
• Add Note annotations for clarity

Phase 5: Quality Check (10 minutes)

Verify completeness:

• - [ ] All documents use consistent terminology
• [ ] Cross-references between docs work
• [ ] Code examples are syntactically correct
• [ ] Mermaid diagrams render properly
• [ ] File paths are accurate
• [ ] Tables are properly formatted
• [ ] Each doc has clear target audience
• [ ] Reading time estimates are realistic
• [ ] Documents are in logical reading order

Output Decision Tree

CODEBLOCK5

Document Templates

Technical Principles Template

CODEBLOCK6
[Directory tree with comments]
project/
├── component-a/ # Purpose
├── component-b/ # Purpose
└── config/ # Purpose

### 2.2 数据分层

[Layer diagram in ASCII]
┌──────────────────┐
│ Layer 3 │ ← Description
└──────────────────┘
▲
│ relationship
│
┌──────────────────┐
│ Layer 2 │ ← Description
└──────────────────┘
CODEBLOCK8

Quick Reference Template

CODEBLOCK9
[Simple flow diagram]
Step1 → Step2 → Step3

- **[Concept 1]**：[Description]
- **[Concept 2]**：[Description]

---

## 🎯 何时使用

| 场景 | 记录位置 | 类别 |
|------|---------|------|
| [Trigger] | [Location] | [Type] |

---

## 📝 记录模板

### [Template Type 1]

markdown
[Actual template content to copy-paste]
CODEBLOCK11

Common Variations

Variation A: Codebase Documentation

For documenting a code repository:

Focus on:

• - Architecture patterns
• API design
• Code organization
• Development workflow
• Testing strategy

Additional diagrams:

• - Class diagrams
• API flow
• Database schema

Variation B: Skill Documentation

For documenting an AI agent skill:

Focus on:

• - When to trigger
• Decision logic
• Output format
• Integration with other skills

Additional sections:

• - Trigger conditions
• Examples of good/bad prompts

Variation C: Tool/Library Documentation

For documenting a tool or library:

Focus on:

• - Installation steps
• Configuration options
• API reference
• Usage examples
• Troubleshooting

Additional sections:

• - Compatibility matrix
• Performance benchmarks

Variation D: Process Documentation

For documenting a workflow or methodology:

Focus on:

• - Step-by-step procedures
• Decision points
• Quality gates
• Roles and responsibilities

Additional diagrams:

• - Swimlane diagrams
• Gantt charts

Gotchas

⚠️ Don't create all 4 docs for simple systems - Use judgment. A 50-line script doesn't need 4 documents.

⚠️ Don't duplicate content - Each document should have a distinct purpose. Cross-reference instead of copy-paste.

⚠️ Don't skip the index - Without navigation, users get lost. The index document is crucial for multi-doc suites.

⚠️ Don't use broken Mermaid syntax - Test diagrams before finalizing. Common errors:

• - Missing closing quotes
• Invalid node IDs
• Unsupported diagram features

⚠️ Don't ignore reading time estimates - Help users plan their time. Be realistic about document length.

⚠️ Don't mix languages inconsistently - If user requests Chinese, use Chinese for all headings and body text. Keep code/commands in original language.

⚠️ Don't assume prior knowledge - Define acronyms and technical terms, especially in Quick Reference.

⚠️ Don't forget visual hierarchy - Use emojis (📖 🎯 💡) and formatting to make docs scannable.

Writing Style Guidelines

For Technical Principles Doc

• - Tone: Academic but accessible
• Depth: Assume reader wants to understand "why" not just "how"
• Code examples: Include actual implementations with explanations
• Length: Don't shy away from detail; this is the deep-dive doc

For Architecture Visualization Doc

• - Diagram-first: Let diagrams tell the story
• Minimal text: Just enough to explain what you're looking at
• Consistent notation: Use same colors/shapes for same concepts
• Progressive complexity: Start simple, add detail gradually

For Quick Reference Doc

• - Tone: Practical and direct
• Format: Heavy use of tables, lists, and code blocks
• No fluff: Every sentence should provide actionable information
• Scannable: Use visual markers (✅ ❌ 🔴 🟢) liberally

For Navigation Index Doc

• - Tone: Welcoming and guiding
• Purpose: Help users find what they need fast
• Structure: Clear hierarchy with visual tables
• Empathy: Anticipate what different users need

Localization

When creating Chinese documentation:

Do:

• - ✅ Use Chinese for all headings and body text
• ✅ Keep technical terms in English within backticks: INLINECODE3
• ✅ Use Chinese punctuation (，。；：)
• ✅ Provide clear Chinese translations for concepts
• ✅ Use emojis universally (work in all languages)

Don't:

• - ❌ Mix English and Chinese in the same sentence without backticks
• ❌ Translate file names or commands
• ❌ Use English-style comma in Chinese text
• ❌ Translate acronyms (keep API as API, not 应用程序接口)

Integration with Other Skills

Pairs well with:

• - self-improvement - After creating docs, log if you learned better documentation patterns
• proactive-agent - Proactively offer to update docs when code changes
• agent-customization - Document your custom skills using this approach

Quality Checklist

Before delivering documentation:

• - [ ] All 4 documents created (or justified why fewer)
• [ ] Reading time estimates in index
• [ ] At least 8 Mermaid diagrams in Architecture doc
• [ ] Quick Reference has copy-paste templates
• [ ] Technical Principles explains "why" not just "what"
• [ ] Index provides learning paths for 3 personas
• [ ] Cross-references between docs work
• [ ] No broken Mermaid syntax
• [ ] Consistent terminology across all docs
• [ ] Each doc has version and last-updated date
• [ ] Troubleshooting section in Quick Reference
• [ ] File tree diagrams use consistent formatting
• [ ] Tables are aligned and complete
• [ ] Code blocks have language specified
• [ ] Chinese localization follows guidelines (if applicable)

Example Prompt Patterns

To trigger this skill:

✅ Good prompts:

• - "当前skill的原理是什么，写一份详尽文档"
• "Write comprehensive documentation for this codebase"
• "Document the architecture with diagrams"
• "Create a quick reference guide and full technical docs"

✅ Clarifying questions (if needed):

• - "Who is the primary audience?" (if unclear)
• "Is this for internal use or public consumption?"
• "Do you need Chinese or English documentation?"

❌ Avoid confusion with:

• - "Write a README" (too vague - might just need one doc)
• "Add comments to the code" (different skill)
• "Create API documentation" (use API-specific skill if available)

Related

• - agent-customization - For creating SKILL.md files specifically
• self-improvement - For logging documentation patterns you discover
• proactive-agent - For maintaining docs over time

Source

• - Created: 2026-03-05
• Origin: Extracted from conversation where comprehensive docs were created for self-improving-agent skill
• Pattern: Successfully applied to document a complex AI agent skill with multiple subsystems
• Validation: Created 4 documents totaling ~13,000 words with 10+ diagrams

---

Note: This skill produces 5,000-15,000 words of documentation. Budget 1-2 hours for complete execution on complex systems.

Tip: Start by reading core files in parallel to save time. The understanding phase is critical - don't rush it.

Remember: Different users need different depths. The layered approach ensures everyone finds what they need. 📚