doc-coauthoring

kriscard's avatarfrom kriscard

Structured workflow for co-authoring documentation, specs, proposals, and decision docs. Use when user wants to write docs, create specs, draft proposals, or similar structured content.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 6, 2026⬇️1downloads
[Technical Writing]

When & Why to Use This Skill

This Claude skill provides a structured, three-stage workflow for co-authoring high-quality documentation, technical specifications, and business proposals. By focusing on context gathering, iterative refinement, and rigorous reader testing, it ensures that complex documents are clear, comprehensive, and accessible to audiences without prior background knowledge.

Use Cases

  • Technical Specification Authoring: Streamline the creation of RFCs, PRDs, or architecture designs by bridging the knowledge gap between technical experts and stakeholders through guided inquiry.
  • Strategic Proposal Development: Draft persuasive business proposals or decision documents using an iterative 'brainstorm-curate-draft' process to ensure every section is refined and aligned with organizational goals.
  • Internal Knowledge Base Creation: Develop self-explanatory SOPs and documentation that are rigorously tested against a 'fresh reader' perspective to eliminate ambiguity and blind spots.
namedoc-coauthoring
descriptionStructured workflow for co-authoring documentation, specs, proposals, and decision docs. Use when user wants to write docs, create specs, draft proposals, or similar structured content.

Document Co-authoring

Guide users through collaborative document creation. Close the context gap first, build iteratively, then verify the document works for readers who have no context.

Three-Stage Workflow

1. Context Gathering  → Close the gap between what you know and what I know
2. Refinement         → Build each section through brainstorm → curate → draft → edit
3. Reader Testing     → Test with fresh perspective to catch blind spots

Stage 1: Context Gathering

Goal: Understand enough to ask smart questions about edge cases.

Initial questions:

  1. What type of document? (spec, proposal, decision doc, RFC)
  2. Who's the primary audience?
  3. What impact should it have when read?
  4. Any template or format to follow?
  5. Key constraints or context?

Then encourage info dumping:

  • Background on problem/project
  • Why alternatives aren't used
  • Org context, timeline pressures
  • Technical dependencies
  • Stakeholder concerns

Ask 5-10 clarifying questions after initial dump.

Exit when: Questions show understanding of edge cases without needing basics explained.

Stage 2: Refinement & Structure

Goal: Build section by section through brainstorm, curate, draft, refine.

For each section:

  1. Clarify: Ask 5-10 questions about what to include
  2. Brainstorm: Generate 5-20 numbered options
  3. Curate: User picks what to keep/remove/combine
  4. Draft: Write the section
  5. Refine: Make surgical edits based on feedback

Section order: Start with the section that has most unknowns. Save summary for last.

After 3 iterations with no changes: Ask what can be removed without losing value.

Stage 3: Reader Testing

Goal: Verify the doc works for someone with no context.

Process:

  1. Predict 5-10 questions readers would ask
  2. Test with fresh perspective
  3. Check: Does the doc answer correctly? Any ambiguity?
  4. Fix gaps found, loop back if needed

Exit when: Fresh reader consistently answers questions correctly.

Output Standards

  • Section-by-section drafts with placeholder structure first
  • Surgical edits (never reprint whole doc)
  • Document works for readers with no prior context
  • Final review checklist before completion

Quick Reference

# Document Brief
Type: [spec/proposal/decision doc/RFC]
Audience: [primary readers]
Impact: [what should reader do/feel/understand]
Constraints: [timeline, format, politics]

# Section Workflow
1. "What should [section] cover?" → 5-10 questions
2. "Here are 15 options for [section]" → numbered list
3. "Which to keep/remove/combine?" → user curates
4. Draft → user feedback → surgical edits
5. Repeat until satisfied