Write a short post from your Product Package

Supports: Developer, week 6 (the demo and the Product Package) and the Master Developer capstone. Time: about three hours of reading and writing.

1. Why this matters

A Product Package holds a lot. Few outside readers will open all of it. Most will read one short page, and if that page is clear, some will open more.

A short post is a good way in for a stranger. It takes one part of the package and says: here is what we did, here is what we learned, and here is what we are not sure about. It points to the package and does not replace it.

A post also tests you. If you cannot explain your roadmap order in 400 words, you may not yet understand it. So the post often improves the package behind it.

This lesson builds on your point of view from lesson 1. You choose a part of the package that supports it, shape a page for a busy reader and use an agent to draft from your facts. You verify every sentence.

The four questions for this lesson

1. What do I decide here? Which part of the package to write about, which claim the post makes, what is shown and what is left out, and what I am willing to say about what does not work yet.
2. What do I delegate to agents, and with what exact brief? A first draft from facts I supply, a shorter version, a check that each claim matches my files, and a plain-words pass (section 5).
3. How do I verify what comes back? I fill a claims table: every sentence is matched to a file, a commit or a link I opened. Anything I cannot match comes out.
4. Which other disciplines are involved? Design (can it be read on a phone?), brand (does it sound like the product?), security and privacy (does any screenshot show something it should not?), support (what will people ask?).

Rung on the agent ladder: delegate. You hand one whole drafting task to an agent with a written brief, and you keep the claim and the checking.

2. Key ideas

Choose the part that earns the post

Pick one part of the package. The best choice is the one that holds your claim from lesson 1. Here is a guide:

If your claim is about	Write from	The post says
A choice between options	A decision record	What we chose, what we gave up, why
The order of the work	The roadmap	Why this epic comes first
What customers need	Interview notes and personas	What we heard that surprised us
How it feels to use	The demo	A walk-through, with the rough parts shown
Who you are as a product	The brand sheet	Why the name and promise are what they are

A decision record is often the best start. It already contains the context, the options and the trade-off, which are what a thoughtful reader wants.

One reader, one question

Write for one real kind of person: a sponsor who funds work like yours, a founder one step behind you or a hiring manager. Decide what that person wants to know, and write the post as the answer. If you write for everybody, you write for nobody.

The shape of a short post

A post that a busy person finishes has this order:

1. A title that states the claim. “Cup swaps are won or lost at the counter” beats “Some thoughts on our trial”.
2. The answer in the first two sentences. Do not make the reader wait.
3. What we did. Two or three sentences of context, with a link to the file.
4. What we saw. The evidence, in plain words.
5. What we do not know. One short paragraph.
6. What happens next. One sentence, or a question to the reader.
7. A disclosure line. What an agent did and what you checked (lesson 3).

Aim for 300 to 600 words. Use short paragraphs and a few headings. Readers of web pages scan before they read: they look at titles, the first words of lines and lists. Put the most important words first. The resources at the end of this lesson explain why.

Show the rough parts: the demo write-up

A demo write-up is a post about the working product. It shows what a user can do now. In week 6 you learned a demo rule: show one thing that is not finished and say so. The same rule holds in writing.

A demo write-up has:

• Who it is for and the problem they have, in one sentence.
• A short walk-through in numbered steps, with screenshots that use fake data.
• One thing that does not work yet, stated plainly.
• What comes next and why that comes next.

Do not use real customer data in screenshots. Do not show a browser tab, a terminal prompt or a settings page that reveals a private address, a name or a key. Check each image before you publish. Describe, do not paste, anything internal.

Plain words

Short sentences. Common words. One idea each. Say “we found” instead of “learnings”. Say “we do not know” instead of “further investigation is warranted”. Explain a technical term the first time it appears. Many readers will be reading in their second language. Read the text aloud: if you would not say a sentence to a friend, rewrite it.

Show, do not boast

Hype words make readers distrust you. “Revolutionary”, “game-changing” and “world-class” tell the reader nothing they can check. Replace each with what you saw: “two owners said the swap was faster than the old way”. If you have no evidence for a strong word, you do not get to use it.

Evidence you can show

Every sentence that states a fact is a promise to the reader. If it says “owners told us”, there must be a note. If it says “the swap takes less time”, there must be a measure you can describe. If it says “most cafés”, say how many you asked. A claims table (Step 5) keeps you honest.

3. Step by step

Step 1: Pick the part and the reader

Open your point-of-view statement. Choose the one Product Package part that best supports it. Write the name of one real kind of reader and the one question they want answered.

Step 2: Write the title and the first two sentences yourself

This is the part an agent should not touch. If it is hard, your claim is not yet clear. Go back to lesson 1.

Step 3: List your facts

List every fact the post may use. Next to each, write where it comes from: a file path, a commit, a note, a link you opened. Include dates and how many people you asked. Leave out any fact you cannot source.

Step 4: Write the brief and run the draft

Use the brief in section 5. Give the agent your title, your first two sentences and your fact list. Ask for a draft that uses only those facts.

Step 5: Build the claims table

Copy every sentence of the draft into a table. For each, write the evidence. Mark each one supported, unsupported or opinion (a view, labelled as such in the text).

Step 6: Cut and repair

Delete or rewrite every unsupported sentence. Replace every hype word and vague word (“many”, “soon”, “significant”) with what you know. If a rewrite needs a new fact, go back to Step 3.

Step 7: Read it as the reader

Read it aloud. Check it on a phone screen. Is the main point in the first two sentences? Are paragraphs short? Does every heading say something?

Step 8: Ask one person

Give it to one person from your reader group. Ask what the post says and what is missing. Change what they got wrong.

Step 9: Save in git

Commit the draft, the facts list, the claims table, the brief and the raw agent output. Publishing comes in lesson 3.

4. Worked example: TrailMug

TrailMug is fictional. The notes and the draft below are invented to show the method.

The founder chooses her decision record, because it holds her claim from lesson 1. Her reader is a founder who runs a small café loyalty scheme and wonders whether to add reusable cups. The reader’s question: “Is it worth the trouble at the counter?”

Her title and first two sentences.

A cup swap scheme is won or lost at the counter If swapping a used cup for a clean one is slower than handing over a paper cup, cafés will quietly stop. We saw the first signs of this in a small trial with two cafés.

Her facts list.

Fact	Source
Trial ran with two partner cafés	trial/README.md
Both owners named the morning rush as their main worry	interviews/03.md, interviews/04.md
My own test with a queue felt slow at the swap step	demo/script.md, line 12
We chose a flat fee, not a per-swap fee	decisions/0001/record.md
We have not tested with real counter staff	trial/README.md

The agent’s first draft included these sentences (invented):

1. “Most cafés worry about speed.” (Unsupported: she asked two.)
2. “Our approach is a game-changer for busy counters.” (Hype.)
3. “Studies show that queues drive customers away.” (No source given. Unsupported.)
4. “Both owners named the morning rush as their main worry.” (Supported.)

Her claims table marked 1 as unsupported and rewrote it “Both of the two owners we asked worried about speed”. She deleted 2. She deleted 3, and wrote beside it: “No study named. If I want this, I find and open one first.” She kept 4.

What she shows. The post ends with a rough part: “We have only tested the swap with me at the counter. Real staff may find it faster, or slower. That is the next thing we test.” It links the decision record and the trial notes.

What she leaves out. The names of the two cafés, because she has not asked them, and a screenshot of her tool settings, because it shows an address she does not want public.

One founder reads it and says: “I did not know whether you had tested it with staff. Now I do.” She keeps that line.

5. Working with AI agents on this

What I decide: the claim, the reader, the title and first two sentences, the facts the post may use, what is left out and whether the post is fit to publish.

What I delegate, with an exact brief. Paste your title, first two sentences and facts list after the brief:

Draft a short post of 300 to 500 words for a reader who is [describe
the reader]. The title and the first two sentences are mine: keep
them exactly.
Use ONLY the facts in my list below. Do not add facts, numbers, names,
studies, quotes, dates or promises. Do not use words like "game-changing",
"revolutionary", "significant", "huge" or "proven".
Structure: what we did, what we saw, what we do not know, what happens
next. Use short sentences, common words and one idea in each. Write so
that a reader whose first language is not English can follow it.
Do not describe a result that my list does not contain.
After the draft, list every sentence that goes beyond my facts, so I can
delete it, and list every place where you were unsure.

FACTS:
- ...

Other tasks, each with its own brief: shorten the draft to a stated word count, keeping every number and date; list words a second-language reader may find hard; turn a walk-through into a short demo script.

How I verify what comes back.

• I fill the claims table (Step 5) from the draft, not only from the agent’s list of extras. That list can miss things.
• I read each number and each name against my facts list.
• I look for adjectives and intensifiers. Claims creep in there.
• I check that the rough parts are still there. Agents tend to smooth them out.
• I open every link and read the finished text aloud.

Which disciplines are involved. Brand and marketing say whether the voice fits. Design says whether it reads well on a phone and whether images have text alternatives. Security and privacy check every screenshot and every name. Support says what questions the post will provoke. Finance checks any claim about cost or savings. I ask each of them for a quick read when the post touches their area.

Disclose. Keep the brief and the raw output in the folder. Plan the one-line disclosure for the post (lesson 3 gives the wording). See Disclose AI use.

What the agent must not do. It must not write the title or first two sentences, must not add facts and must not publish anything. A person publishes.

Where this sits on the ladder. This lesson is on the delegate rung: a whole drafting task, a written brief, acceptance criteria (the claims table) and your own review. Orchestrate would run several sessions at once, for example one drafting and another hunting for unsupported claims, each reading the same facts list. Govern is a written rule, for example “a post may be merged only when its claims table has no unsupported row”. Lesson 3 shows a small version.

6. Common mistakes

• Writing about the whole package. One post, one part, one claim.
• Burying the point. Put the answer in the first two sentences.
• Letting the agent write the claim. You would be publishing an opinion you did not form.
• Giving the agent no facts. It will fill the gap with plausible text.
• Keeping the hype. Replace “game-changer” with what you saw, or delete it.
• Smoothing out the rough parts. The line about what does not work yet is the one readers trust.
• A screenshot with private details. Check every image, including the edges.
• Using real customers. Do not name them, describe them in a way that identifies them or quote them without asking.
• Publishing the same day. Leave a night. The morning shows what you overclaimed.

7. Practice: write the post and keep the claims table

Deliverable: files in thought-leadership/posts/ in your product’s git repository. Use the point of view from lesson 1.

1. draft.md: the post, 300 to 600 words, with the title, first two sentences, the sections from section 2 and links to your Product Package files. Or a demo write-up with who it is for, the walk-through, one thing that does not work yet and what comes next.
2. facts.md: your facts list with a source for each.
3. claims.md: the claims table with every sentence, its evidence and a mark: supported, unsupported or opinion. At the end, no row may be unsupported.
4. agent-brief.md and agent-output.md: the exact brief and the raw, unedited draft.
5. review-notes.md: what you changed and why, who you asked and what they said.

Commit with a message such as Add draft post, facts and claims table. Do not publish yet.

Check: read it aloud. Count how many sentences go beyond your facts list. The number should be zero.

Stretch: write the post again for a second reader, for example a sponsor. Write two lines on what changed.

8. Checklist

• The post makes one claim, stated in the title and the first two sentences, written by me.
• It names one kind of reader and answers one question.
• It comes from one part of my Product Package and links to the files.
• Every fact has a source in facts.md.
• The claims table has no unsupported row.
• No hype words, and no vague words where a number or a date is known.
• It says what I do not know or what does not work yet.
• Every image is checked for private details and uses fake data.
• One person read it and told me what they understood.
• The brief and the raw agent output are in the repository.

9. Further learning

The resources below this lesson help you write plainly and structure a page. The essay on writing like you talk gives you a simple test for every sentence. Google’s technical writing course and the free beginner guide teach clear sentences and good lists. The Nielsen Norman Group article explains how people scan a page, and the GOV.UK pages on content design show how to start from what the reader needs. The Write the Docs guide helps when your write-up is a how-it-works page or demo that lives beside your code. In the next lesson you share the post honestly: disclosure, hype, private details, a human approval step and corrections.