# Writing a good brief

The brief decides the draft. A good one is the difference between a draft you rewrite and a draft you edit, and it is worth two extra minutes every time. This page is about what to put in a brief. To learn where you type it, see [Draft a document with Workover AI](/docs/draft-a-document/).

**Before you start:** Your workspace needs an AI provider chosen under **Settings** > **AI**, either **Workover AI** (included with a paid plan) or **Your own key**. See [Choose who provides Workover AI](/docs/choose-ai-provider/).

## The four things that matter most

**Who is reading, and what 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.** State the outcome, not the topic. “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. Workover does not copy your house format from your other documents, so the brief is where it comes from.

**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 prompt box sends your brief when you press **Enter**. To start a new line, as in the strong brief above, press **Shift+Enter**.

## Give it the material

If the piece depends on facts, put the facts in front of it rather than hoping.

- **Technical topics:** link a code repository to the project so the draft is written from the code. Name the directory or file that matters in the brief. “Document the webhook payloads in `apps/api/src/modules/webhooks`” is a better instruction than “document our webhooks”, for the same reason it would be to a new engineer. See [Grounding drafts in your code repository](/docs/grounding-drafts-in-github/).
- **Your existing documents:** the drafter does not look up your other documents by name. If a new piece must agree with an existing one, paste the relevant passage into the brief.
- **Images:** you can paste up to 4 images into the prompt box on your workspace home, for example a screenshot of a written brief or of the UI copy you are documenting.

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 every draft and revision. Keep the brief about this piece.

## What happens when you submit

Depending on the brief and the project, Workover may ask you something before it starts writing:

- **A brief that reads like several articles** gets a plan to review first. You can approve it with **Draft N articles** (N is the number of articles in the plan), or choose **Write one article instead**.
- **A technical brief in a project with a linked repository**, on a provider that can read it, may prompt a question about whether to read the code first. On the workspace home, choose **Check the repo** to ground the draft in the repository, or **Draft now** to write from the brief alone. On the **New document** page, the same choice is **Read the repo** or **Skip it**.

## Iterate rather than restart

If the draft is 70% right, ask for the change rather than rewriting the brief. Revisions you ask for with **Iterate**, in the document’s AI tab, arrive as tracked suggestions, so it is cheap to try one. See [Revising a document with AI](/docs/iterating-on-a-draft/).

## Related

- [How Workover AI works](/docs/ai-drafting-overview/)
- [Draft a document with Workover AI](/docs/draft-a-document/)
- [Style guides](/docs/style-guides/)
- [Revising a document with AI](/docs/iterating-on-a-draft/)
- [Grounding drafts in your code repository](/docs/grounding-drafts-in-github/)