writing-documentation（编写文档）

Writing Documentation Skill

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

When to Use This 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)

Workflows

Workflow 1: Write New Documentation

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?

1. Load writing principles

- Read reference/strunk-white-principles.md to internalize core principles

1. Determine documentation type

- Read reference/doc-types.md to select appropriate type - Identify essential sections based on guidelines

1. Draft the documentation

- Apply Strunk & White principles while writing

1. Validate quality

- Run through Quality Checklist (below) - Verify all essential information is present - Confirm document achieves its purpose

Workflow 2: Improve Existing Documentation

Steps:

1. Read the current documentation

- Understand its purpose and audience - Note specific problems (verbosity, unclear sections, missing info)

1. Load writing principles

- Read reference/strunk-white-principles.md - Review reference/examples.md for before/after patterns

1. Apply improvements

- Remove needless words - Convert passive to active voice - Strengthen vague statements - Eliminate redundancy - Improve organization if needed

1. Validate improvements

- Run through Quality Checklist - Verify no information was lost - Confirm clarity improved

Workflow 3: Review Documentation

Steps:

1. Load writing principles

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

1. Assess against quality criteria

- Run through Quality Checklist (below) - Note specific violations with examples

1. Provide feedback

- List specific issues found - Reference violated principles - Suggest concrete improvements

Decision Framework

When to Write vs Improve

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

Prioritizing Conciseness vs Comprehensiveness

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

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

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.

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