Agent Skills: Writing Documentation Skill

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?

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

Workflow 2: Improve Existing Documentation

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

Workflow 3: Review Documentation

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

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