On this page12
- Why do people stop reading product updates?
- The User-First Stack: five layers in a fixed order
- A worked rewrite of a typical update post
- What to cut from an update post
- Opening lines by type of update
- Where does the update fit into the bigger story?
- Where should you post product updates?
- FAQ
- How long should a product update post be?
- Should product updates include screenshots or video?
- How often should we publish product updates?
- Who should write product updates, product or marketing?
A product update announcement people actually finish starts with the change for the user in one plain sentence, then tells them who it's for and how to use it, and only then gets into why you built it and the technical detail. Most update posts run in the opposite order, starting with the team's excitement and ending with the part readers needed. Flip the order, cut anything the user can't act on, and link the full changelog instead of pasting it.
Why do people stop reading product updates?
Because the first three lines are about you.
"We're thrilled to announce the latest release of our platform, which represents months of hard work from the team." A reader has learned nothing they can use. They scroll on, and the actual change (gas fees are lower, or the mobile app now supports a new chain) sits in paragraph four where nobody sees it.
There's a second reason, specific to crypto. Many update posts are written for the team's peers, not for users. They lead with the architecture, the client version, the new proving system. Some readers care. Most want to know whether anything is different when they open the app.
Clarity is so so underrated in web3. Shilika Jain on X, 27 Aug 2023
I still believe it. Clarity in an update post is mostly a question of order.
The User-First Stack: five layers in a fixed order
This is the structure I use for every update post I write or edit. Five layers, always in this order. Readers can stop after any layer and still leave with something useful.
| Layer | What it answers | Length | Good opening words |
|---|---|---|---|
| 1. The change | What's different for me | One sentence | "You can now", "You no longer need to", "It's now cheaper to" |
| 2. Who it's for | Does this apply to me | One or two sentences | "If you", "For anyone who" |
| 3. How to use it | What do I do | Three steps or fewer | Numbered steps, a link, a screenshot |
| 4. Why we built it | Where does this fit | One short paragraph | The user problem, the feedback, the bigger idea |
| 5. The detail | How does it work | As long as needed | Technical notes, limits, link to changelog |
Layer 1 is the headline and the first line. Layers 1 to 3 should fit on a phone screen without scrolling. Layer 4 is where the update joins your wider story. Layer 5 is for the readers who want everything, and it's fine if most people never reach it.
The test is simple: if someone reads only the first two sentences, do they know what changed and whether it affects them? If not, rewrite the top.
A worked rewrite of a typical update post
Here's a draft of the kind I see often, for a made-up DeFi app.
Before:
Big news, fam! After months of building, v2.4 is LIVE. This release includes a refactored routing engine, upgraded oracle integration, a new design system and several UX improvements. Huge shoutout to the team. More to come!
It's energetic. It's also empty. "Refactored routing engine" means nothing to a user until you say what it does for them.
After:
Headline: Swaps on the app now cost less and fail less often.
If you swap tokens on the app, you'll now get routed through more pools automatically, which means better prices on larger trades and fewer failed transactions when the market moves fast.
Nothing to do on your side. Open the app and swap as usual.
Why: failed swaps were the top complaint in our last community call. The new routing engine checks more liquidity sources before it sends your trade.
Full technical notes and the oracle change are in the changelog.
Same release. The second one tells the reader what happened to them, in the order they care about. Notice the "after" barely mentions the design system. If it doesn't change anything a user does, it goes in the changelog.
(These are illustrative drafts, not a real product.)
What to cut from an update post
Cutting is most of the editing work. My standard cut list:
- "We're excited / thrilled / proud to announce." Readers assume you're happy about your own release.
- Version numbers in the headline, unless your users actually track them (developers sometimes do).
- Every change that has no visible effect for users. Link them instead.
- Internal codenames.
- Thank-you lists for the team. Celebrate them in a separate post where they get proper credit.
- "More to come" and "stay tuned." Either say what's next or say nothing.
- Emoji used as bullet points for technical items. They make dense lists harder to scan, not easier.
There's a deeper version of this cut. If you find you can't write layer 1 because no user-facing change exists, ask whether the release needed an announcement at all.
Advice to web3 founders: Stop adding useless features and just launch:) Shilika Jain on X, 12 Apr 2023
A small fix can go in the changelog and a weekly roundup. Not every merge deserves its own post, and posting every one of them trains people to ignore you. The sibling post on announcement fatigue covers how to space and bundle them.
Opening lines by type of update
Different updates need different first sentences. Here are the patterns I reach for.
| Update type | First line pattern | Example shape |
|---|---|---|
| New feature | "You can now [action]" | You can now stake directly from the mobile app |
| Improvement | "[Thing] is now [faster / cheaper / easier]" | Withdrawals now settle in minutes instead of hours |
| Fix | "We fixed [problem you may have hit]" | We fixed the issue where some wallets showed a zero balance |
| New chain or asset | "[Asset/chain] users can now [action]" | Base users can now bridge in without leaving the app |
| Breaking change or deprecation | "On [date], [thing] will stop working. Here's what to do." | On a set date the old API version stops; switch by following three steps |
| Fee or pricing change | "From [date], [fee] changes from X to Y" | State the old and new numbers plainly, then the reason |
The last two rows matter most and get written worst. When something is being taken away or getting more expensive, lead with the date and the action users need to take, and put the reason after. Burying a fee change under "exciting updates" is how you end up with a community thread full of angry screenshots.
Where does the update fit into the bigger story?
Layer 4 is where an update stops being a changelog entry and becomes part of the narrative you're building. One or two sentences connecting this change to the bigger idea you stand for.
If your project's story is "self-custody should be as easy as an exchange," then a faster recovery flow isn't just a feature. It's evidence for the thesis. Say so, briefly. Over a quarter, those small connections add up, and the next big announcement lands on readers who already know where you're going.
That's the difference between an audience and a list of people who downloaded your app once.
the biggest brands in future will have a loyal community as opposed to just buyers. Shilika Jain on X, 27 Dec 2022
Keep layer 4 short, though. One paragraph. Big moments like a mainnet, a token or a major user milestone deserve a fuller story arc, and the sibling post on milestone storytelling handles those.
Where should you post product updates?
The same structure works everywhere, but trim it per channel:
- Blog or docs: all five layers. This is the canonical version others link to.
- X: layers 1 and 3 in the first post, with a screenshot or short clip. Layer 4 as a reply if it adds something. Link to the blog.
- Discord or Telegram announcements: layers 1 to 3, plus a link. Pin it if users need to act.
- Email or newsletter: layer 1 as the subject line, layers 1 to 4 in the body.
- In-app: layer 1 only, with a "learn more" link.
When this doesn't fit: protocol-level releases aimed only at node operators or integrators. Those readers want the technical detail first, and that's fine. Write them a proper technical release note and keep the user-facing version separate.
If writing these consistently is the bottleneck, it's part of the content writing work I do with teams: a template, a few rewrites, and an editing pass until the team can do it without me. The same "user change first" thinking also shapes how I approach partnership announcements.
FAQ
How long should a product update post be?
Long enough for the five layers and no longer. For a single feature that's usually 150 to 400 words on the blog, plus a much shorter social version. If you're past 800 words, you probably have two updates in one post or a changelog that should be a link.
Should product updates include screenshots or video?
Yes, if the change is visible. A screenshot of the new screen or a 15-second clip of the flow does more than a paragraph of description. Skip it for backend changes where there's nothing to see, and don't use mockups that don't match what users will actually get.
How often should we publish product updates?
Match the cadence to how often users notice change. Weekly or biweekly roundups work for fast-shipping teams, with standalone posts saved for changes that need action or carry real news. Publishing every small merge on its own trains people to scroll past.
Who should write product updates, product or marketing?
Product should supply the facts and the "why," and someone with an editor's eye should own the final order and wording. The best results I've seen come from a product manager drafting layers 1 to 3 and marketing tightening the whole thing. Engineers are invaluable for layer 5.
Shipping something soon and want the update post to land? Book a 30-minute review and send me the draft first.
