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.

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.

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.
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 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.