documenting-systems
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseTechnical Documentation
技术文档撰写
For writing style, tone, and voice guidance, use with The Engineer persona.
Skill(ce:writer)如需写作风格、语气和语态方面的指导，请结合工程师角色使用。
Skill(ce:writer)Core Principles
核心原则
1. Progressive Disclosure
1. 渐进式信息披露
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.
分层次展示信息：
| 层级 | 内容 | 用户问题 |
|---|---|---|
| 1 | 一句话描述 | 它是什么？ |
| 2 | 快速入门代码块 | 如何使用它？ |
| 3 | 完整API参考 | 有哪些可用选项？ |
| 4 | 架构深度解析 | 它的工作原理是什么？ |
警告、破坏性变更和前置条件需放在最顶部。
2. Task-Oriented Writing
2. 任务导向型写作
markdown
<!-- Bad: Feature-oriented -->markdown
<!-- Bad: Feature-oriented -->AuthService Class
AuthService Class
The AuthService class provides authentication methods...
<!-- Good: Task-oriented -->The AuthService class provides authentication methods...
<!-- Good: Task-oriented -->Authenticating Users
Authenticating Users
To authenticate a user, call login() with credentials:
undefinedTo authenticate a user, call login() with credentials:
undefined3. Show, Don't Tell
3. 示例优先，避免空泛说明
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
- 标题采用句子式大小写：使用“Getting started”而非“Getting Started”
- 最多3级标题：层级过深时应拆分文档
- 代码块必须指定语言
- 内部链接使用相对路径
- 结构化数据（含3个及以上属性）使用表格展示
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
- 代码示例经过测试且可运行
- 无占位文本或TODO项
- 与实际代码行为一致
- 无需通读即可快速浏览获取信息
- 读者明确下一步操作
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.
如需README、API端点和文件组织模板，请查看references/templates.md。
Related Skills
相关技能
- - Writing style, tone, and voice (load The Engineer persona)
Skill(ce:writer) - - Architecture and flow diagrams
Skill(ce:visualizing-with-mermaid)
- - 写作风格、语气和语态（加载工程师角色）
Skill(ce:writer) - - 架构与流程图
Skill(ce:visualizing-with-mermaid)