Doc Co-Writing

---
name: doc-co-writing
description: Co-writes a document in three stages - gather the writer's context, build it section by section with review pauses, then test whether it works for a reader who was not in the room. Use for proposals, reports, specs, decision documents and articles where getting it right matters more than getting it fast.
license: Apache-2.0
metadata:
  source: anthropics/skills
---

# Doc Co-Writing

You write the document with the person, not for them. They hold the context and the judgment; you hold the structure and the drafting. Nothing gets written before the two of you agree what goes in it.

Offer this shape at the start: three stages, roughly "tell me everything", "build it one section at a time", "check it works on someone who was not here". If they would rather work freeform, do that instead. The workflow is a service, not a toll gate.

## Stage 1: Get the context out of their head

Open with five questions, and tell them shorthand answers are fine:

1. What kind of document is this?
2. Who reads it?
3. What should happen after they read it?
4. Is there a template or format to follow?
5. Anything else you need to know about the situation?

Then ask them to dump everything they have, unorganized. Background, related discussions, why the obvious alternatives were rejected, team dynamics and history, deadlines, technical constraints, who will object and to what. Tell them not to tidy it: getting it out matters more than the order it arrives in.

When they are done, ask 5 to 10 numbered questions about the gaps. Number them so they can answer "1: yes, 2: ask Dana, 3: no, backwards compatibility" and move on.

**You have enough context when your questions are about edge cases and trade-offs rather than basics.** That is the signal to move on. Ask if there is anything else they want to add, then start.

If they point you at documents or threads you can actually reach, read them. If an existing document has images with no text description, mention it: anyone who later reads the document through an assistant cannot see those images, so the information in them is invisible.

## Stage 2: Build it section by section

**Agree the structure first.** Propose 3 to 5 sections with a one-line purpose each, or ask which sections they want if they already know. Start with the section holding the most unknowns, usually the core proposal or the technical approach. Summaries go last, when you know what you are summarizing.

Create the file with every section heading in place and a one-line note under each saying what belongs there. It gives you both something to work against.

Then, for each section:

1. **Ask 5 to 10 clarifying questions** about what this section should cover.
2. **Brainstorm 5 to 20 candidate points.** Numbered. Include things they mentioned earlier and may have forgotten, and angles nobody has raised yet. Offer to generate more.
3. **Let them curate.** "Keep 1, 4, 7. Remove 3, it repeats 1. Combine 11 and 12." Ask for a one-line reason where it is not obvious; the reasons teach you their priorities and make the next section faster.
4. **Ask what is missing** before drafting.
5. **Draft that section only.** Do not race ahead.
6. **Edit surgically.** Change the lines they name and confirm the change. Never reprint the whole document to fix one paragraph.

Ask them to tell you what to change rather than editing the draft themselves, at least early on, because their instructions are what teach you their voice. If they do edit directly, read what they changed and carry it forward.

Keep a short running list of decisions so section six does not contradict section two.

When three rounds pass with only cosmetic changes, ask what could be cut without losing anything. That question does more for a document than another round of polish.

**As you approach the end**, read the whole thing and report on: flow between sections, anything repeated or contradictory, generic filler that carries no weight, and any sentence that could go without the reader noticing.

## Stage 3: Test it on a reader

The author cannot judge whether a document works, because they cannot un-know the context. So test it on someone who does not have it.

1. **Predict the questions.** Write 5 to 10 questions a real reader would arrive with.
2. **Ask a fresh reader.** Either a separate assistant session with only the document and the question, or a colleague who was not involved. The key is no shared context.
3. **Run three extra checks.** What is ambiguous or unclear? What knowledge does this document assume the reader already has? Are there internal contradictions?
4. **Report honestly what the reader got wrong**, and fix those sections. A wrong answer is almost never the reader's failure.

Repeat until the reader answers correctly and turns up nothing new.

## Finishing

Tell them plainly: they own this document, so they should read it end to end themselves, check every fact, link and number, and confirm it does what they wanted it to do. Offer one last review if they want it.

Two things worth suggesting at the end: put depth in an appendix rather than the main body, and update the document once real readers have reacted to it.

## Output shape

- **Stage 1**: the five questions, then the numbered gap questions.
- **Stage 2**: the section list for approval, then per section - questions, a numbered idea list, the draft, and a short "your call" line asking what to change.
- **Stage 3**: the predicted reader questions, what the fresh reader answered, and the specific gaps you are fixing.
- **The end**: the finished document, plus a note on what you smoothed in the final pass.

## Rules

- Never draft before the structure is agreed. Structure disagreements found at the end cost the whole draft.
- One section at a time, with a pause. The pause is the point.
- Do not add facts, numbers or claims they have not given you or approved.
- Match their voice. If you cannot hear it yet, ask for something they have written.
- If drafting a section shows the outline was wrong, stop and fix the outline before writing more.
- Be direct and procedural. Do not sell the process while running it.

## Example

**Request.** "I need to write a decision doc for moving our team off the shared build server."

**Stage 1** surfaces what the request did not say: the audience is two engineering managers and a finance lead, the real goal is approval for a spend, an earlier attempt was rejected for being too technical, and there is a renewal deadline six weeks out. None of that was in the original sentence, and all of it changes the document.

**Stage 2** produces a five-section outline (the problem in cost terms, what we tried, the proposal, alternatives rejected, what we need from you), starting with the proposal because that is where the unknowns are. The brainstorm for that section offers 14 points; they keep 6, cut 5 as too technical for the finance reader, and combine 2. The drafted section runs 200 words instead of the 800 the first attempt would have produced.

**Stage 3** asks a fresh reader "what is being asked for, and how much does it cost?" The reader gets the cost right but answers the ask as "approval to evaluate options", when the actual ask is approval to sign. That single wrong answer sends one section back for a rewrite, and it is exactly the failure that sank the previous attempt.

## Edge cases

- **They are short on time.** Compress, do not skip. Three sections instead of five, one review pause per section, and a single reader question at the end.
- **They want to write parts themselves.** Ask which. Draft the rest, and match their sections' voice rather than imposing yours.
- **They keep answering "whatever you think".** Stop asking open questions and offer two concrete options with a recommendation.
- **The document is being written to justify a decision already made.** Say so plainly, and write it as a decision record rather than a proposal. The reader will notice either way.
- **There is a template they must follow.** Follow it exactly, and put the good structure inside the required headings.
- **The reader test keeps failing on the same point.** That is usually a missing piece of context, not weak wording. Go back to stage 1 for that one thing.

## Files

- `references/examples.md` - a full decision-document run from first question to reader test, a reader test that found a real blind spot, and the compressed version for someone with one afternoon. Read before your first stage-2 section.

## Attribution

Adapted from the `doc-coauthoring` skill in [anthropics/skills](https://github.com/anthropics/skills/tree/main/skills/doc-coauthoring), Apache-2.0. The three-stage workflow, the brainstorm-then-curate loop, the surgical-editing rule and the reader-testing stage come from there. The worked runs and the edge cases are ours.

# Worked runs

One document from first question to finished, one reader test that saved a document, and the compressed version for someone with an afternoon.

## Contents

- [Run 1: a decision document, end to end](#run-1-a-decision-document-end-to-end)
- [Run 2: a reader test that found a blind spot](#run-2-a-reader-test-that-found-a-blind-spot)
- [Run 3: the compressed version](#run-3-the-compressed-version)
- [Patterns worth copying](#patterns-worth-copying)

---

## Run 1: a decision document, end to end

**Request.** "I need to write a decision doc about moving our team off the shared build server."

### Stage 1

The five opening questions, and what came back:

| Question | Answer |
| --- | --- |
| What kind of document? | Decision doc, needs sign-off |
| Who reads it? | Two engineering managers, one finance lead |
| What should happen after? | They approve a 14k annual spend |
| Template? | None, but the last one was rejected |
| Anything else? | Renewal deadline in six weeks |

The info dump added the part that mattered most: the previous attempt was rejected as "too in the weeds", and the finance lead had asked a question nobody answered, which was what happens to the money currently spent on the shared server.

Gap questions asked, answered in shorthand:

1. What does the shared server cost today, all in? - "about 9k, plus the two days a month Sam spends on it"
2. What breaks if you do nothing? - "nothing breaks, builds just stay at 40 minutes"
3. Who else uses the shared server? - "platform team, they are staying"
4. Has finance approved anything like this before? - "yes, the CI seat expansion last year"
5. What is the reversal cost if this is wrong? - "one month, no contract lock-in"

Question 5 turned out to be the one that carried the decision.

### Stage 2

Outline agreed in one round:

1. What this costs us today (in money and hours)
2. What we tried
3. The proposal
4. What we are not doing, and why
5. What we need from you

Started with section 3, where the unknowns were. The brainstorm produced 14 candidate points. Curation:

```text
Keep 2, 3, 5, 8, 9, 12
Remove 1 (too technical for the finance reader)
Remove 4, 6, 7 (implementation detail, belongs in an appendix)
Remove 10 (repeats 3)
Combine 11 and 13 into one line about the migration window
```

The reasons were the useful part. Two of them, "too technical for the finance reader" and "implementation detail", became a rule applied to every later section without needing to be repeated.

The drafted section came to 190 words. The pre-workflow version of this document had 800 words in the equivalent section, which is why nobody finished reading it.

Running decisions kept alongside the draft:

```text
- Money framing throughout, hours converted to cost
- No tool names in the body, appendix only
- The ask is approval to sign, not approval to evaluate
- Reversal cost gets its own line - it is the strongest argument
```

That last line came from stage 1 question 5 and would have been lost otherwise.

### Stage 3

See run 2 below, which is this document's reader test.

---

## Run 2: a reader test that found a blind spot

**Predicted reader questions:**

1. What is being asked for, and how much does it cost?
2. What happens if we say no?
3. Why not just fix the shared server?
4. Who else is affected?
5. What if this turns out to be wrong?

**What the fresh reader answered**, given only the document:

| Question | Answer | Verdict |
| --- | --- | --- |
| 1 | "Approval to evaluate dedicated build machines, around 14k" | **Wrong on the ask** |
| 2 | "Builds stay slow, roughly 2 days of engineer time a month" | Correct |
| 3 | "The platform team owns it and has other priorities" | Correct |
| 4 | "Nobody else, the platform team keeps using the shared server" | Correct |
| 5 | "Not clearly stated" | **Gap** |

Two findings, and both were fatal to the document's purpose.

The ask was written as "we would like to move to dedicated build machines this quarter", which reads as the start of a conversation. The document was asking for a signature. One sentence fixed it: "We are asking you to approve 14k of annual spend at the 6 March renewal, so the team can move before the current contract auto-renews."

The reversal cost was in the author's head, from a stage 1 answer, and never made it onto the page. Added as its own line, because a decision that can be undone in a month with no contract lock-in is a much easier decision to approve.

**The extra checks** surfaced one more thing: the phrase "engineering hours" appeared in section 1 and "developer time" in section 3, and the reader treated them as two different quantities. Made consistent.

**Second reader test**: all five answered correctly, nothing new surfaced. Done.

**Why this stage exists.** The author had read the document eleven times and could not see either problem, because they knew what the ask was. Nobody who knows the answer can test whether the document gives it.

---

## Run 3: the compressed version

**Request.** "I have one afternoon and I need a project update that our director will actually read."

Compressing without abandoning the shape:

- **Stage 1** cut to three questions: who reads it, what should happen after, what have they already been told. Info dump kept, but capped at one message.
- **Stage 2** cut to three sections, brainstormed 6 points each instead of 15, one review pause per section rather than the full question-brainstorm-curate loop.
- **Stage 3** cut to two reader questions, asked once: "what is the status of this project, and is anything at risk?"

Total elapsed: about 90 minutes, and the reader test still caught something. The fresh reader answered "at risk" for a workstream the author considered fine, because the document mentioned a slipped date in one section without saying it had been absorbed. One clause fixed it.

**The judgment call.** The temptation under time pressure is to drop stage 3, because it feels like the optional one. It is the cheapest stage and the only one that tells you something you do not already know. Cut the brainstorming instead.

---

## Patterns worth copying

1. Ask what happened to the last attempt. The reason it failed is usually the most useful fact in stage 1.
2. Make them curate a numbered list rather than react to a draft. Reactions to a draft only reach what is already written.
3. Write down the reasons behind their cuts. Two or three of them become rules for the whole document.
4. Keep a running decisions list. It is what stops section six contradicting section two.
5. Test with a reader who has no context, and treat every wrong answer as a document defect.
6. Under time pressure, compress the stages rather than dropping the last one.