> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt
> Use this file to discover all available pages before exploring further.

# Doc Co-Authoring

> Structured workflow for collaboratively creating documentation, proposals, specs, and decision docs

# Doc Co-Authoring Workflow

The Doc Co-Authoring skill provides a structured, three-stage workflow for creating high-quality documentation. It helps users efficiently transfer context, refine content through iteration, and verify the document works for readers before sharing.

## When to Use

Trigger this skill when:

* User mentions writing documentation: "write a doc", "draft a proposal", "create a spec", "write up"
* User mentions specific doc types: "PRD", "design doc", "decision doc", "RFC"
* User is starting a substantial writing task that needs structure

**Supported document types**: Technical specs, decision documents, proposals, RFCs, PRDs, design docs, status reports, project plans

## Workflow Overview

The skill guides you through three distinct stages:

<Accordion title="Stage 1: Context Gathering">
  **Goal**: Close the gap between what you know and what Claude knows

  * Gather meta-context about the document (type, audience, purpose)
  * Collect background information through info dumps
  * Ask clarifying questions to fill knowledge gaps
  * Pull context from connected tools (Slack, Google Drive, etc.)
</Accordion>

<Accordion title="Stage 2: Refinement & Structure">
  **Goal**: Build the document section by section through iteration

  * Create document structure with sections
  * For each section: ask questions, brainstorm options, curate, draft, refine
  * Use surgical edits rather than full rewrites
  * Learn your style and preferences as you go
</Accordion>

<Accordion title="Stage 3: Reader Testing">
  **Goal**: Verify the document works for readers without context

  * Test with a fresh Claude instance (no context bleed)
  * Predict and verify common reader questions
  * Identify blind spots and ambiguities
  * Fix gaps before others read it
</Accordion>

## Stage 1: Context Gathering

The first stage focuses on transferring knowledge efficiently.

### Initial Questions

Claude will ask for meta-context:

1. What type of document is this?
2. Who's the primary audience?
3. What's the desired impact when someone reads this?
4. Is there a template or specific format to follow?
5. Any other constraints or context to know?

<Tip>
  Answer in shorthand or dump information however works best for you. You don't need to organize it - just get the context out.
</Tip>

### Information Dumping

Provide context through multiple methods:

* Stream-of-consciousness info dumps
* Links to team channels or threads
* Shared documents (Google Drive, SharePoint)
* Related discussions or decisions
* Organizational context (team dynamics, politics)
* Timeline pressures or constraints

<Note>
  If integrations are available (Slack, Google Drive, etc.), Claude can pull context directly. Otherwise, paste relevant content or enable connectors in Claude settings.
</Note>

### Clarifying Questions

After initial context, Claude generates 5-10 numbered questions based on gaps. You can answer:

* In shorthand: "1: yes, 2: see #channel, 3: no because backwards compat"
* By linking to more docs
* By pointing to channels to read
* By continuing to info-dump

**Exit condition**: You've gathered sufficient context when questions show deep understanding - edge cases and trade-offs can be discussed without needing basics explained.

## Stage 2: Refinement & Structure

This stage builds the document iteratively, section by section.

### Document Structure

Claude will suggest 3-5 sections appropriate for your doc type, or use your provided template. The structure is created with placeholders:

* **With artifacts** (Claude.ai): Creates an artifact you can view and reference
* **Without artifacts**: Creates a markdown file in your working directory

<Tip>
  Start with the section that has the most unknowns - usually the core decision/proposal for decision docs, or the technical approach for specs. Save summaries for last.
</Tip>

### Section-by-Section Process

For each section, follow this iterative process:

<Accordion title="Step 1: Clarifying Questions">
  Claude asks 5-10 questions about what should be included in this specific section.

  Answer in shorthand or indicate what's important to cover.
</Accordion>

<Accordion title="Step 2: Brainstorming">
  Claude generates 5-20 possible points to include, based on:

  * Context you've shared
  * Angles or considerations not yet mentioned
  * Section-specific requirements

  You'll see things you may have forgotten plus new perspectives.
</Accordion>

<Accordion title="Step 3: Curation">
  Indicate which points to keep, remove, or combine:

  * "Keep 1,4,7,9"
  * "Remove 3 (duplicates 1)"
  * "Remove 6 (audience already knows this)"
  * "Combine 11 and 12"

  Freeform feedback also works - Claude will extract your preferences.
</Accordion>

<Accordion title="Step 4: Gap Check">
  Claude asks if anything important is missing before drafting.
</Accordion>

<Accordion title="Step 5: Drafting">
  Claude drafts the section using `str_replace` to update the document.

  Instead of editing directly, tell Claude what to change. This helps it learn your style for future sections.
</Accordion>

<Accordion title="Step 6: Iterative Refinement">
  Provide feedback on the draft:

  * "Remove the X bullet - already covered by Y"
  * "Make the third paragraph more concise"
  * "Add more technical detail about the implementation"

  Claude makes surgical edits without reprinting the whole doc.
</Accordion>

### Quality Checking

After 3 iterations with no substantial changes, Claude asks if anything can be removed without losing important information. This keeps the document tight and focused.

<Note>
  The process repeats for all sections. As you work through sections, Claude learns your preferences and style, making later sections faster and more aligned.
</Note>

## Stage 3: Reader Testing

The final stage verifies your document works for readers without your context.

### Testing Methods

<Accordion title="With Sub-Agents (Claude Code)">
  Claude performs testing automatically:

  1. **Predict Reader Questions**: Generates 5-10 realistic questions readers would ask
  2. **Test with Fresh Claude**: Each question is tested with a new Claude instance that only sees the document (no conversation context)
  3. **Run Checks**: Tests for ambiguity, false assumptions, and contradictions
  4. **Report Results**: Identifies what Reader Claude got right/wrong

  If issues are found, Claude loops back to refinement for problematic sections.
</Accordion>

<Accordion title="Without Sub-Agents (Claude.ai)">
  You perform testing manually:

  1. **Generate Questions**: Claude suggests 5-10 questions readers would ask
  2. **Open Fresh Session**: You open [https://claude.ai](https://claude.ai) in a new conversation
  3. **Test Questions**: Paste/share the document and ask Reader Claude each question
  4. **Check Understanding**: Note what Reader Claude answers correctly or misinterprets
  5. **Additional Checks**: Ask Reader Claude about ambiguities, assumptions, and contradictions
  6. **Report Back**: Tell Claude what Reader Claude struggled with, and it will fix those gaps
</Accordion>

### Exit Condition

When Reader Claude consistently answers questions correctly and doesn't surface new gaps or ambiguities, the document is ready.

<Tip>
  This testing phase catches blind spots before your actual audience reads the document. It's especially valuable when stakeholders will paste your doc into Claude to understand it.
</Tip>

## Final Review

Before completion, Claude recommends:

1. Do a final read-through yourself - you own this document
2. Double-check facts, links, and technical details
3. Verify it achieves the impact you wanted
4. Consider linking the conversation in an appendix
5. Use appendices for depth without bloating the main doc

## Workflow Tips

### Tone and Approach

* Direct and procedural - no unnecessary sales pitch
* Brief rationale when it affects your behavior
* You always have agency to adjust the process

### Handling Deviations

* Want to skip a stage? Claude can switch to freeform writing
* Feeling frustrated? Claude can suggest ways to move faster
* You control the pace and depth of each stage

### Context Management

* Claude proactively asks when context is missing
* Gaps are addressed as they come up, not accumulated
* The more context provided early, the better the output

<Note>
  Artifacts are used for drafting full sections, while `str_replace` is used for all edits. Brainstorming lists stay in conversation - they don't need artifacts.
</Note>

## Best Practices

1. **Front-load context**: The more context in Stage 1, the smoother Stage 2 becomes
2. **Start with complex sections**: Build the hardest parts first while context is fresh
3. **Be specific with feedback**: "Make it shorter" is less helpful than "Remove the technical jargon for non-technical readers"
4. **Let Claude learn your style**: Indicate changes rather than editing directly, especially early on
5. **Trust the reader testing**: Fresh eyes (even AI eyes) catch what authors miss

## Document Types Supported

The workflow adapts to various document types:

* **Technical Specs**: Focus on architecture, implementation, and technical decisions
* **Decision Docs**: Emphasize options considered, trade-offs, and the chosen path
* **Proposals**: Highlight problem, solution, impact, and resource requirements
* **RFCs**: Structure around problem statement, proposed solution, alternatives, and open questions
* **PRDs**: Cover user needs, features, success metrics, and timeline

## Related Skills

* **Internal Comms**: For structured internal communication formats (3P updates, newsletters)
* **Brand Guidelines**: To apply brand styling to completed documents