Doc Coauthoring

---
name: doc-coauthoring
description: Use when co-authoring docs, proposals, or technical specs.
tags: [documentation, writing, proposals, specs, collaboration]
related_skills: [internal-comms]
---

# Doc Co-Authoring Workflow

A structured workflow for guiding users through collaborative document creation in three stages: Context Gathering, Refinement & Structure, and Reader Testing.

## When to Use

Offer this workflow when the user mentions:
- Writing documentation, a proposal, or spec
- Creating a PRD, design doc, decision doc, or RFC
- Starting any substantial writing task

## Stage 1: Context Gathering

**Goal**: Close the gap between what the user knows and what you know.

### Initial Questions
1. What type of document is this?
2. Who's the primary audience?
3. What's the desired impact?
4. Is there a template or format to follow?
5. Any other constraints?

### Information Dump
Encourage the user to dump all context:
- Background on the project/problem
- Related discussions or shared documents
- Why alternatives aren't being used
- Organizational context and politics
- Timeline pressures
- Technical dependencies
- Stakeholder concerns

### Clarifying Questions
When the user signals they're done, ask 5-10 clarifying questions based on gaps.

## Stage 2: Refinement & Structure

**Goal**: Build the document section by section.

For each section:
1. Ask clarifying questions about what to include
2. Brainstorm 5-20 options
3. User selects what to keep/remove/combine
4. Draft the section
5. Iteratively refine through edits
6. Quality check: ask if anything can be removed

### Section Ordering
Start with whichever section has the most unknowns (usually the core proposal). Summary sections are best left for last.

## Stage 3: Reader Testing

**Goal**: Test the document with a fresh reader to catch blind spots.

1. Predict what questions readers might ask
2. Test with a fresh agent (no context bleed)
3. Run additional checks for ambiguity and contradictions
4. Fix gaps based on results

## Common Pitfalls

- ❌ **Skipping context gathering** — Leads to generic, unfocused documents
- ❌ **Writing full doc in one pass** — Iterate section by section
- ❌ **Not testing with fresh eyes** — Author blind spots are real
- ❌ **Over-engineering** — Not every doc needs the full workflow; adapt to the task

## Verification Checklist

- [ ] Context gathering completed with documented key decisions
- [ ] All sections drafted and refined through iterations
- [ ] Reader testing performed with fresh reader
- [ ] No ambiguities or contradictions found
- [ ] Document achieves the intended impact
- [ ] User has done final read-through