writing-documentation_skill

Overview

This skill produces concise, clear technical documentation by applying Elements of Style principles. It is designed for writing or improving project docs, API references, tutorials, and architecture or design documents. Use it to make documentation more direct, scannable, and useful for readers.

How this skill works

The skill starts by determining purpose and audience, then loads core writing principles to guide edits. It chooses the appropriate document type, drafts or revises content using active voice and omission of needless words, and validates output against a quality checklist. Feedback is specific, with concrete edits and examples where helpful.

When to use it

• Writing new project or API documentation and guides
• Improving existing documentation for clarity and concision
• Reviewing docs for style, structure, and completeness
• When a user asks to “make this more concise” or “improve clarity”
• Preparing tutorials, architecture, or design documents (not code comments)

Best practices

• Begin by defining the document’s purpose and target readers
• Load and apply core Elements of Style principles before editing
• Prefer active voice and definite, concrete language
• Balance concise overviews with linked deep dives for complex topics
• Validate that no essential information was removed during edits

Example use cases

• Draft a quick-start and overview for a new project so users can get started fast
• Convert a verbose guide into a scannable tutorial with step-by-step examples
• Improve an API reference by clarifying parameter behavior and adding minimal examples
• Review architecture docs to tighten prose and ensure decision rationale is explicit
• Edit CLI or command reference entries to include full context and executable examples