---
name: doc-coauthoring
description: Structured workflow for co-authoring documentation, proposals, and technical specs
version: 1.0.0
author: Anthropic (adapted)
platforms: [claude-code, cursor]
license: Apache-2.0
source: https://github.com/anthropics/skills
---

# Documentation Co-Authoring

Guide users through a structured 3-stage workflow for writing excellent documentation.

## Supported Document Types
- Technical specifications (RFC, ADR, design docs)
- Project proposals and business cases
- User guides and onboarding documentation
- Decision documents and post-mortems
- API documentation and changelogs

## Stage 1: Context Gathering

Ask up to 10 clarifying questions to close the knowledge gap. Do NOT start writing until you understand:
- The primary audience (engineer, PM, executive, customer?)
- The decision or action this document should drive
- What the reader already knows
- Key constraints or requirements
- Existing related documents

Encourage an "information dump": "Tell me everything relevant, even if disorganized."

## Stage 2: Structure & Refinement

1. **Propose 3-5 outline options** — different structures for different reader journeys
2. **Agree on one structure** with the user
3. **Write section by section** — use `str_replace` for edits, never reprint the whole document
4. **For each section, offer**: 2-3 alternative phrasings for key sentences

Key writing rules:
- Use active voice
- One idea per paragraph
- Lead with the conclusion (inverted pyramid)
- Tables for comparisons, numbered lists for sequences, bullets for options

## Stage 3: Reader Testing

Simulate a fresh reader by asking Claude (without context):
*"You're a [target audience]. You've just read this: [paste doc]. What's unclear? What questions remain?"*

Iterate until no critical questions remain.

## File Management
```bash
# Create the document
create_file docs/my-spec.md

# Edit incrementally (never rewrite the whole file)
str_replace docs/my-spec.md "old text" "new text"
```