writing-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Writing Documentation Skill

文档撰写Skill

Apply Strunk & White's Elements of Style principles to produce concise, clear technical documentation.

运用Strunk & White的《风格的要素》（Elements of Style）原则生成简洁、清晰的技术文档。

When to Use This Skill

何时使用此Skill

Use this skill when:

Writing new documentation (README, API docs, guides, tutorials, architecture docs)
Improving existing documentation
Reviewing documentation for quality
User asks to "make this more concise" or "improve clarity"
User mentions: documentation, docs, README, guide, tutorial, API docs

Do NOT use this skill for:

Code comments (different context, separate skill needed)
Marketing copy (requires persuasive voice, not neutral clarity)
Personal blog posts (requires individual voice)

适合使用此Skill的场景：

撰写新文档（README、API文档、指南、教程、架构文档）
优化现有文档
评审文档质量
用户要求“让内容更简洁”或“提升清晰度”
用户提及：documentation、docs、README、guide、tutorial、API docs

不适合使用此Skill的场景：

代码注释（场景不同，需使用单独的技能）
营销文案（需要有说服力的语气，而非中立清晰的表述）
个人博客文章（需要体现个人风格）

Workflows

工作流程

Workflow 1: Write New Documentation

工作流程1：撰写新文档

Steps:

Understand the purpose
- What is the primary goal of this documentation?
- Who is the target audience?
- What do readers need to accomplish after reading?
Load writing principles
- Read
```
reference/strunk-white-principles.md
```
  to internalize core principles
Determine documentation type
- Read
```
reference/doc-types.md
```
  to select appropriate type
- Identify essential sections based on guidelines
Draft the documentation
- Apply Strunk & White principles while writing
Validate quality
- Run through Quality Checklist (below)
- Verify all essential information is present
- Confirm document achieves its purpose

步骤：

明确文档目的
- 此文档的核心目标是什么？
- 目标受众是谁？
- 读者阅读后需要完成什么任务？
学习写作原则
- 阅读
```
reference/strunk-white-principles.md
```
  ，内化核心原则
确定文档类型
- 阅读
```
reference/doc-types.md
```
  ，选择合适的文档类型
- 根据指南确定必要的章节
撰写文档草稿
- 撰写时应用Strunk & White原则
验证质量
- 对照下方的质量检查表进行检查
- 确认所有必要信息已涵盖
- 验证文档是否达成预期目的

Workflow 2: Improve Existing Documentation

工作流程2：优化现有文档

Steps:

Read the current documentation
- Understand its purpose and audience
- Note specific problems (verbosity, unclear sections, missing info)
Load writing principles
- Read
```
reference/strunk-white-principles.md
```
- Review
```
reference/examples.md
```
  for before/after patterns
Apply improvements
- Remove needless words
- Convert passive to active voice
- Strengthen vague statements
- Eliminate redundancy
- Improve organization if needed
Validate improvements
- Run through Quality Checklist
- Verify no information was lost
- Confirm clarity improved

步骤：

阅读现有文档
- 理解其目的和受众
- 记录具体问题（冗长、表述模糊、信息缺失）

学习写作原则

阅读
```
reference/strunk-white-principles.md
```
查看
```
reference/examples.md
```
中的前后对比示例

实施优化
- 删除冗余词汇
- 将被动语态转换为主动语态
- 强化模糊表述
- 消除重复内容
- 必要时优化文档结构
验证优化效果
- 对照质量检查表进行检查
- 确认没有丢失信息
- 验证清晰度已提升

Workflow 3: Review Documentation

工作流程3：评审文档

Steps:

Load writing principles

Read
```
reference/strunk-white-principles.md
```
Review relevant guidelines in
```
reference/doc-types.md
```

Assess against quality criteria
- Run through Quality Checklist (below)
- Note specific violations with examples
Provide feedback
- List specific issues found
- Reference violated principles
- Suggest concrete improvements

步骤：

学习写作原则

阅读
```
reference/strunk-white-principles.md
```
查看
```
reference/doc-types.md
```
中的相关指南

对照质量标准评估
- 对照下方的质量检查表进行检查
- 记录具体的违规示例
提供反馈
- 列出发现的具体问题
- 引用被违反的原则
- 提出具体的改进建议

Decision Framework

决策框架

When to Write vs Improve

撰写新文档vs优化现有文档

Write new documentation when:

No documentation exists
Existing documentation is fundamentally wrong or outdated
Complete restructuring needed (cheaper to rewrite)

Improve existing documentation when:

Core structure and information are sound
Style or clarity issues can be fixed incrementally
Specific sections need enhancement

撰写新文档的场景：

无现有文档
现有文档存在根本性错误或已过时
需要彻底重构（重写比修改更高效）

优化现有文档的场景：

核心结构和信息是合理的
风格或清晰度问题可以逐步修正
特定章节需要优化

Choosing Documentation Type

选择文档类型

See

reference/doc-types.md

for detailed guidelines. Quick reference:

README: Project overview, quick start, primary entry point
API Documentation: Reference for function/endpoint signatures and behavior
Tutorial/Guide: Step-by-step learning path for accomplishing specific goals
Architecture/Design Doc: Explain system structure, decisions, and tradeoffs
CLI Tool Documentation: Command reference with options and examples

详细指南请见

reference/doc-types.md

。快速参考：

README：项目概述、快速开始、主要入口文档
API Documentation：函数/接口签名及行为的参考文档
Tutorial/Guide：完成特定目标的分步学习路径
Architecture/Design Doc：解释系统结构、决策及权衡
CLI Tool Documentation：包含选项及示例的命令参考

Prioritizing Conciseness vs Comprehensiveness

简洁性vs全面性的优先级

Prioritize conciseness when:

Documentation type is reference (README, API docs, CLI docs)
Readers need to scan quickly
Getting started / quick start sections

Prioritize comprehensiveness when:

Documentation type is learning-focused (tutorials, guides)
Complex concepts require detailed explanation
Architecture decisions need thorough justification

Balance both:

Use concise overview sections with detailed subsections
Link to comprehensive resources rather than embedding everything
Apply progressive disclosure pattern

优先考虑简洁性的场景：

文档类型为参考类（README、API文档、CLI文档）
读者需要快速浏览
入门/快速开始章节

优先考虑全面性的场景：

文档类型为学习类（教程、指南）
复杂概念需要详细解释
架构决策需要充分的论证

平衡两者：

在简洁的概述章节后设置详细的子章节
链接到全面的资源而非嵌入所有内容
采用渐进式披露模式

Quality Checklist

质量检查表

Content

内容

Writing (Core Principles)

写作（核心原则）

Structure

结构

Technical Documentation

技术文档

Reference Files

参考文件

When to Load Each Reference

何时加载各参考文件

Load
reference/strunk-white-principles.md
:

At the start of EVERY documentation writing/improvement task
When reviewing documentation

Load
reference/doc-types.md
:

When choosing what type of documentation to write
When unsure about essential sections for a doc type
When reviewing documentation structure

Load
reference/examples.md
:

When improving existing documentation (see patterns)
When you want concrete before/after examples

加载
reference/strunk-white-principles.md
的场景：

开始任何文档撰写/优化任务前
评审文档时

加载
reference/doc-types.md
的场景：

选择要撰写的文档类型时
不确定某类文档的必要章节时
评审文档结构时

加载
reference/examples.md
的场景：

优化现有文档时（参考示例模式）
需要具体的前后对比示例时

Common Pitfalls

常见陷阱

Skipping Principle Loading: ALWAYS load

reference/strunk-white-principles.md

before writing.

Following Guidelines Rigidly: Adapt to the specific project's needs. Some projects don't need all sections; some need additional ones.

Over-Editing: "Omit needless words" means remove words that add no value. Keep all information that serves the reader's purpose.

Sacrificing Accuracy for Brevity: Accuracy always wins. Express explanations concisely, but never misleadingly.

Inconsistent Terminology: Choose one term for each concept and use it consistently.

跳过原则学习：撰写前务必加载

reference/strunk-white-principles.md

。

僵化遵循指南：需根据具体项目需求调整。部分项目不需要所有章节，部分项目需要额外章节。

过度编辑：“删除冗余词汇”指移除无价值的词汇。保留所有对读者有价值的信息。

为简洁牺牲准确性：准确性永远优先。简洁地表达解释，但绝不能产生误导。

术语不一致：为每个概念选择一个术语并保持一致使用。

Notes

注意事项

This skill works iteratively - you can run it multiple times on the same document without degrading quality (idempotent)
Quality over quantity - a short, clear document is better than a comprehensive, confusing one

此Skill支持迭代使用——可对同一文档多次运行而不会降低质量（幂等性）
质量优先于数量——简短清晰的文档优于全面但混乱的文档