Back to Details

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:
  1. Understand the purpose
    • What is the primary goal of this documentation?
    • Who is the target audience?
    • What do readers need to accomplish after reading?
  2. Load writing principles
    • Read 
      reference/strunk-white-principles.md
      to internalize core principles
  3. Determine documentation type
    • Read 
      reference/doc-types.md
      to select appropriate type
    • Identify essential sections based on guidelines
  4. Draft the documentation
    • Apply Strunk & White principles while writing
  5. Validate quality
    • Run through Quality Checklist (below)
    • Verify all essential information is present
    • Confirm document achieves its purpose
步骤：
  1. 明确文档目的
    • 此文档的核心目标是什么？
    • 目标受众是谁？
    • 读者阅读后需要完成什么任务？
  2. 学习写作原则
    • 阅读
      reference/strunk-white-principles.md
      ，内化核心原则
  3. 确定文档类型
    • 阅读
      reference/doc-types.md
      ，选择合适的文档类型
    • 根据指南确定必要的章节
  4. 撰写文档草稿
    • 撰写时应用Strunk & White原则
  5. 验证质量
    • 对照下方的质量检查表进行检查
    • 确认所有必要信息已涵盖
    • 验证文档是否达成预期目的

Workflow 2: Improve Existing Documentation

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

Steps:
  1. Read the current documentation
    • Understand its purpose and audience
    • Note specific problems (verbosity, unclear sections, missing info)
  2. Load writing principles
    • Read 
      reference/strunk-white-principles.md
    • Review 
      reference/examples.md
      for before/after patterns
  3. Apply improvements
    • Remove needless words
    • Convert passive to active voice
    • Strengthen vague statements
    • Eliminate redundancy
    • Improve organization if needed
  4. Validate improvements
    • Run through Quality Checklist
    • Verify no information was lost
    • Confirm clarity improved
步骤：
  1. 阅读现有文档
    • 理解其目的和受众
    • 记录具体问题（冗长、表述模糊、信息缺失）
  2. 学习写作原则
    • 阅读
      reference/strunk-white-principles.md
    • 查看
      reference/examples.md
      中的前后对比示例
  3. 实施优化
    • 删除冗余词汇
    • 将被动语态转换为主动语态
    • 强化模糊表述
    • 消除重复内容
    • 必要时优化文档结构
  4. 验证优化效果
    • 对照质量检查表进行检查
    • 确认没有丢失信息
    • 验证清晰度已提升

Workflow 3: Review Documentation

工作流程3：评审文档

Steps:
  1. Load writing principles
    • Read 
      reference/strunk-white-principles.md
    • Review relevant guidelines in 
      reference/doc-types.md
  2. Assess against quality criteria
    • Run through Quality Checklist (below)
    • Note specific violations with examples
  3. Provide feedback
    • List specific issues found
    • Reference violated principles
    • Suggest concrete improvements
步骤：
  1. 学习写作原则
    • 阅读
      reference/strunk-white-principles.md
    • 查看
      reference/doc-types.md
      中的相关指南
  2. 对照质量标准评估
    • 对照下方的质量检查表进行检查
    • 记录具体的违规示例
  3. 提供反馈
    • 列出发现的具体问题
    • 引用被违反的原则
    • 提出具体的改进建议

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

内容

  • Purpose is clear
  • Essential information is present
  • No unnecessary information
  • Correct and accurate
  • 目的明确
  • 包含所有必要信息
  • 无冗余信息
  • 内容准确无误

Writing (Core Principles)

写作（核心原则）

  • Active voice predominates
  • Definite statements (not hedging)
  • Positive form
  • Specific, concrete language
  • Concise (no needless words)
  • 以主动语态为主
  • 表述明确（不含含糊其辞）
  • 采用肯定句式
  • 使用具体、具象的语言
  • 简洁（无冗余词汇）

Structure

结构

  • Logical organization
  • Clear headings
  • Scannable
  • Examples where helpful
  • 逻辑清晰
  • 标题明确
  • 易于浏览
  • 必要时配有示例

Technical Documentation

技术文档

  • Code examples are executable
  • Commands include full context
  • Prerequisites are stated
  • Error cases are covered
  • 代码示例可执行
  • 命令包含完整上下文
  • 明确列出前置条件
  • 涵盖错误场景

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支持迭代使用——可对同一文档多次运行而不会降低质量（幂等性）
  • 质量优先于数量——简短清晰的文档优于全面但混乱的文档