# Writing a good brief

The brief decides the draft. This is the difference between something you rewrite and something you edit, and it is worth two extra minutes every time.

## The four things that matter most

**Who is reading, and what do they already know.** “For developers integrating our API” and “for marketers evaluating us” produce different pieces from the same topic. Without this the draft is written for nobody.

**What the reader should be able to do afterwards.** Not the topic — the outcome. “Explain webhooks” gives you an encyclopedia entry. “Get someone from zero to a working webhook endpoint” gives you a guide.

**The shape.** How long, what sections, whether it needs a comparison table, whether code samples are expected. If you know the structure, say it; the model will not guess your house format.

**What to avoid.** The claim you cannot make, the competitor you do not name, the feature that is not shipped yet. Constraints are cheap to state and expensive to fix afterwards.

## A weak brief and a strong one

Weak:

```
Write a blog post about content workflows.
```

Strong:

```
For content leads at 10-50 person SaaS companies who publish to
WordPress and currently review in Google Docs.

After reading, they should understand why the copy-paste step between
document and CMS is where their published pages drift from what was
approved, and what to do about it.

~900 words. Open with the concrete failure, not a definition. One
section per failure mode with a short example. No feature pitch until
the last two paragraphs. Don't name competitors.
```

The second one is 90 seconds of typing and saves an hour.

## Give it the material

If the piece depends on facts, point at them rather than hoping. Connect the [GitHub repository](/docs/grounding-drafts-in-github) for anything technical. Reference your existing documents so it builds on them instead of contradicting them.

A draft grounded in real sources is checkable. One written from general knowledge reads just as confidently and has to be verified line by line.

## Let the style guide carry tone

Do not spend the brief describing your voice — put that in the [style guide](/docs/style-guides) once and it applies to everything. Keep the brief about *this* piece.

## Iterate rather than restart

If the draft is 70% right, ask for the change rather than rewriting the brief. Revisions arrive as tracked suggestions, so it is cheap to try one. See [iterating on a draft](/docs/iterating-on-a-draft).

## Related

- [Drafting with AI](/docs/ai-drafting-overview)
- [Style guides](/docs/style-guides)
- [Iterating on a draft](/docs/iterating-on-a-draft)