Public Writing

---
name: public-writing
description: How to write a page that people outside the agent sessions read. Examples are a public roadmap, a business proposal, a stakeholder update, a launch page, and a pitch. Use it before you draft or edit such a page. It does not cover replies in chat or documents that only agents read.
---

# Writing for people

These rules come from two product sessions in October 2026. One wrote a public roadmap, and one wrote a product proposal for the business side of a team. They add to the writing rules of the project. They do not replace them.

## Name the reader first

Before you write, name the reader, and what the reader must do after reading. The reader sets the form:

- A busy reader inside the business scans. Use bullets, the opening included.
- A public reader follows a story. Give one message in each paragraph, and link each section to the next one. Remind the reader of the point before, because people forget.

If the page has both kinds of reader, ask the owner which one comes first.

## The reader

- Write for a reader who knows nothing of the delivery work. Words such as "release", "sprint", or "ticket" are jargon to that reader. Use the word that the reader uses.
- Name people as the reader sees them. For a reader on the team, write "users", not "you".
- A reader takes an example as the whole set. Say "for example", and give an example that does not mislead.
- Tie each section to the goal that the owner named.

## The order

- Get the reader to agree first. Name the problem in the words of the reader. Show numbers only after that. A score such as "4 of 7 covered" convinces only the team.
- Put the key message where the eye lands, in a pull quote or a highlighted box, not in body text. One pattern that works is a grey line of context, then a colored answer box.

## Honesty

- Report progress as it is. If a part is half done, say that it is half done.
- Show no number that means nothing to the reader. If a measure has no data yet, write "Not launched. No data."
- Make no claim of success. Show what changed, and let the reader judge.
- Use a plain human voice. Avoid AI phrasing: decorative groups of three, a clause that starts with ", and each", and a closing line that praises the work.

## Level of detail

- A proposal stays at a high level. Numbers, rule names, and permissions go in a note in the decision record. The team reads that note when the work starts.
- Before you add a block, read the sections around it again. Put the block where the reader needs it, add a sentence that links it, and remove what it now repeats.

## Sources

- The body holds no ticket numbers, file names, rule numbers, or internal notes.
- Each claim still has a source. List the sources in a folded note at the bottom of the page.

## Design

- Use a display font for titles, a short label over each section title, and bold on the key phrases. A "no bold" rule for reports does not cover these pages.
- Set caveats and disclaimers apart, in smaller grey italic text.
- Give each page visuals: icons, one illustration, and photos or app screenshots beside the text.
- Use a photo only under a free license, such as the Unsplash License. Download it only with the owner's yes.
- Take app screenshots with test data only.
- Embed each image in the page, so that the page works on its own.
- A product proposal shows a mock wireframe of its first step.

## A roadmap

- A roadmap shows what users get, when, and why. Give each period equal weight.
- A small feature does not go on a roadmap. Put it in the backlog.

## The review

- Offer three or four titles, and let the owner pick. A label is not a title.
- Deliver the page where the owner can comment in place, for example an artifact. For each comment, reply, make the change, and resolve the thread.
- Apply each comment to the whole page, not only the part that it names. Keep one tone from top to bottom.
- A human reads text differently from an AI. Expect many small comments.
- Ask the owner one question in each reply.