coauthoring-documents

Document Co-Authoring Workflow

A structured approach to collaborative document creation that produces high-quality, reader-tested content.

When to Offer This Workflow

Suggest this workflow when users mention:

• Writing documentation or guides
• Creating proposals or pitches
• Drafting technical specifications
• Preparing decision documents
• Developing any structured content

Give users agency - they can skip stages or work freeform if preferred.

The Three Stages

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  STAGE 1        │     │  STAGE 2        │     │  STAGE 3        │
│  Context        │ ──► │  Refinement     │ ──► │  Reader         │
│  Gathering      │     │  & Structure    │     │  Testing        │
└─────────────────┘     └─────────────────┘     └─────────────────┘

---

Stage 1: Context Gathering

Goal: Close knowledge gaps through meta-questions before writing.

Questions to Cover

1. Document type: What kind of document is this?
2. Audience: Who will read this? What do they already know?
3. Desired impact: What should readers think/feel/do after reading?
4. Format constraints: Length, style guide, template requirements?
5. Success criteria: How will you know if it's good?

Information Gathering

Encourage users to "information dump":

• Background context and history
• Previous discussions and decisions
• Constraints and requirements
• Existing materials to reference
• Stakeholder concerns

Exit Criteria

Move to Stage 2 when you have sufficient context to:

• Understand edge cases
• Anticipate reader questions
• Make informed structural decisions

---

Stage 2: Refinement & Structure

Goal: Build the document section by section with iterative refinement.

Section-by-Section Process

For each section:

1. Ask clarifying questions about this section's content
2. Brainstorm options (5-20 possibilities)
3. Curate selections - identify best approaches
4. Check for gaps - what's missing?
5. Draft content - write the section
6. Iterate - refine based on feedback

Working Strategy

• Start with unknowns: Begin with sections that have the most uncertainty
• Use scaffolding: Create structure first, then fill in details
• Make surgical edits: Use str_replace for targeted changes, not full rewrites
• Track preferences: Note what the user likes/dislikes for consistency

Editing Approach

DON'T: Reprint entire document for small changes
DO: Make targeted edits to specific sections

Example:
"I'll update the introduction paragraph. Here's the change:

Old: The system handles user authentication...
New: The authentication system provides secure user verification..."

Exit Criteria

Move to Stage 3 when:

• All sections are drafted
• User is satisfied with overall structure
• Major content decisions are finalized

---

Stage 3: Reader Testing

Goal: Verify the document works for readers without author context.

Testing Methods

Option A: Fresh Claude Instance

Use a sub-agent to read the document cold:

"Read this document as if you're the target audience.
What questions do you have?
What's confusing or unclear?
What assumptions does it make?"

Option B: Manual Testing

User can:

1. Open a new conversation
2. Paste the document
3. Ask for critique from target audience perspective

What to Check

• Ambiguity: Are any statements open to misinterpretation?
• False assumptions: Does it assume knowledge readers may not have?
• Contradictions: Do any parts conflict with each other?
• Missing context: Are there unexplained references?
• Unclear conclusions: Are takeaways explicit and actionable?

Predict Reader Questions

For each section, ask:

• What will readers want to know next?
• What might they disagree with?
• What needs more evidence or examples?

Iteration Loop

Reader Testing → Identify Issues → Targeted Fixes → Re-test

Repeat until:

• No major questions remain
• Document stands alone without author explanation

---

Key Principles

Quality Over Speed

• Take time to explore options
• Don't rush through stages
• Better to iterate more than publish prematurely

Meaningful Improvements

Each iteration should make substantial improvements:

• Not just wordsmithing
• Address actual content gaps
• Improve clarity and structure

User Agency

• Respect user's preferred pace
• Allow skipping or combining stages
• Adapt to their working style

Context Accumulation

• Don't let gaps accumulate
• Address uncertainties when they arise
• Build understanding incrementally

---

Document Types & Templates

Technical Specification

# [Feature Name] Technical Specification

## Overview
[1-2 sentence summary]

## Background
[Context and motivation]

## Requirements
### Functional Requirements
### Non-Functional Requirements

## Proposed Solution
### Architecture
### Implementation Details
### Alternatives Considered

## Timeline & Milestones

## Open Questions

Decision Document

# [Decision Title]

## Status
[Proposed/Accepted/Deprecated]

## Context
[What is the issue we're addressing?]

## Decision
[What was decided]

## Consequences
### Positive
### Negative

## Alternatives Considered

User Documentation

# [Feature/Product] Guide

## Overview
[What this does and why it matters]

## Getting Started
[Quick start steps]

## Core Concepts
[Key ideas to understand]

## How-To Guides
[Task-oriented instructions]

## Reference
[Detailed specifications]

## Troubleshooting
[Common issues and solutions]

---

Tips for Success

1. Front-load context gathering - invest time upfront to save iterations later
2. Be explicit about stage transitions - "Ready to move to refinement?"
3. Encourage rough drafts - perfect is the enemy of good
4. Test with real scenarios - use concrete examples in reader testing
5. Document decisions - note why certain approaches were chosen