Heldinhow/doc-coauthoring

Document Coauthoring

Overview

Document coauthoring is a structured workflow for creating high-quality technical documentation, proposals, specifications, and decision documents through iterative collaboration. This skill should be invoked when users want to write documentation, proposals, specs, or decision docs that require careful structuring and multiple rounds of refinement.

Core Principles

• Iteration Over Perfection: Build documents incrementally through multiple drafts rather than attempting perfection in one pass
• Reader-Centric: Always write with the target audience in mind - their expertise level, goals, and potential questions
• Structured Organization: Use clear headings, logical flow, and visual hierarchy to make documents scannable
• Testable Output: Documents should be testable by having fresh readers validate comprehension

Preparation Checklist

• [ ] Identify the document type (spec, proposal, decision doc, tutorial)
• [ ] Define the target audience and their expertise level
• [ ] Clarify the purpose - what decision should this document enable?
• [ ] Gather existing context, references, and requirements

Step-by-Step Process

1. Stage 1 - Context Gathering: Ask clarifying questions about scope, audience, key points to cover
2. Stage 2 - Outline & Draft: Build the document structure first, then fill in content section by section
3. Stage 3 - Iteration: Review, refine, and expand based on feedback
4. Stage 4 - Validation: Test with a fresh instance to catch blind spots and gaps
5. Stage 5 - Polish: Final review for clarity, consistency, and formatting

Do's and Don'ts

• ✅ Do create an outline before writing - structure first, content second
• ✅ Do use concrete examples to illustrate abstract concepts
• ✅ Do keep paragraphs short - aim for 3-4 sentences maximum
• ❌ Don't write long walls of text without headings or bullet points
• ❌ Don't skip the validation stage - fresh eyes catch gaps
• ❌ Don't use jargon without defining it for non-expert readers

Anti-Patterns

• The Infinite Draft: Continuously revising without ever finalizing the document
• Assumption of Knowledge: Using acronyms or terms without definition
• Feature Creep: Adding nice-to-have sections that dilute the main message
• The Empty Document: Staring at a blank page instead of starting with a rough outline