Before announcing a breaking product change in public, write and rehearse the migration note. Explain who is affected, what stops working, how to move to the new behavior, and what to do if the move fails. If those instructions are unclear, the release announcement is early.
Building in public makes the change visible to people who are curious about your work. Some of them also depend on the current behavior. A good explanation respects both groups, with the affected user's next action taking priority over the founder's launch story.
Identify the behavior that people depend on
Start with the current workflow, not the implementation diff. A database column can change without affecting a user. A small change in an exported file can break somebody's carefully maintained import.
Write down what a person can do today and what they will be able to do after the release. Include defaults, permissions, saved settings, file formats, and integrations where they matter. These are prompts for an impact check, not a claim that every change touches all of them.
Ask who relies on the old behavior. You may have evidence from support conversations, documentation, or authorized product records. If you don't know, state that uncertainty and investigate before treating the change as harmless.
A feature's low visible usage does not prove that nobody depends on it. A monthly export may matter a great deal to the person who uses it once a month.
Separate a changelog entry from migration instructions
Keep a Changelog recommends a curated record for people and explicitly includes changes, deprecations, and removals. That is a useful foundation. A list of changes still needs instructions when a reader must act.
A changelog entry tells the reader what changed in a release. A migration note explains how to preserve or deliberately change an existing workflow. A public founder update can then explain the reason and the tradeoff.
These documents can link to each other without repeating every detail. Keep one maintained place for the actual steps. A social post is a poor location for the only copy of instructions that may need correction.
Don't call a change an improvement for everyone if a known group loses something. State the affected behavior plainly, even when the new design is better for the product's main use case.
Rehearse a fictional CSV migration
Imagine a fictional scheduling SaaS that exports appointment data. The existing export puts the customer's displayed name in the first column. A planned export adds a stable booking identifier first and moves the name to the second column.
That sounds minor until an existing spreadsheet reads the first column as a name. A founder who tests only whether the new file downloads will miss the broken handoff.
The migration note should identify the affected group: people whose saved imports select fields by position. It should explain the new layout and provide an example file with invented data. It should distinguish that group from readers who open each export manually.
This is an illustrative scenario, not a report about Buildside or a real customer's system. Its purpose is to show how a public announcement can be accurate about a feature while still omitting the user's most important task.
Test the old and new path with the same example
Prepare an example that works through the old workflow. Save the expected result. Then use equivalent invented input through the proposed new workflow and inspect the result at the receiving end.
In the scheduling example, the relevant finish is a correctly populated spreadsheet. The download completing is only an intermediate step. Check whether names, identifiers, times, and empty values arrive where the documented steps say they will.
Keep a comparison path where the old workflow remains unchanged. That helps distinguish a problem introduced by the migration from a problem that already existed in the example.
Record what you checked and what you didn't. One spreadsheet application or one importer is a bounded test. It is not proof that every downstream tool will accept the new format.
Write instructions a reader can follow without your help
Describe the starting condition before the first action. A person needs to know whether these instructions apply to their account, export version, or saved setup.
Then explain the actions in the order the user will take them. Use the exact visible names that exist in the shipped interface. If a step requires an option you have not implemented, the note has found unfinished work.
Include a check after the change. “Import one example and confirm the name is in the name field” is more useful than “Make sure everything works.” A reader should know how to detect a failed migration before relying on the output.
Have someone unfamiliar with the change read the instructions against the test setup. If you have to explain a missing step aloud, revise the written version. Report that review as completed only if it actually happened.
Decide what happens when the migration fails
A useful note needs a recovery path that the product can support. That might be returning to the earlier format, keeping the old workflow temporarily, or contacting a defined support route before proceeding.
Don't promise a rollback just because it would make the announcement reassuring. Some changes cannot be reversed cleanly after new data is written. Describe the actual boundary and make the implementation decision before publishing the instructions.
For the fictional export, the founder could choose to keep the original layout as the default while offering the new layout separately. That is one possible design, not a universal requirement.
The alternative might be a carefully announced replacement with a clear transition period. Which choice fits depends on the evidence, the cost of supporting both paths, and the impact on people who rely on the old one.
Announce the user action before the founder story
Open the public release post with the affected behavior and any required action. Place a link to the maintained migration note where a reader can find it immediately.
Explain the reason after the reader knows what to do. You might describe why stable identifiers solve a recurring import problem. Avoid presenting an internal cleanup as a customer benefit without explaining the connection.
Be careful with availability. A release note drafted in advance should not imply that the new behavior is already live. When access varies, say which version or group can use it.
A screenshot can show the new export option, but it cannot prove that an existing importer still works. Use the screenshot to explain the interface and the rehearsal to evaluate the workflow.
Use public feedback to find missing cases
Sharing the migration explanation with relevant peers can reveal assumptions. Someone may notice that the note omits timezones, saved mappings, or the handling of blank fields.
Buildside connects founders sharing work in public. I founded it. A useful question for other builders is whether the proposed instructions make the affected workflow clear.
Peer review complements checks with actual intended users. Another developer may understand the format while missing a business-specific dependency. Keep that distinction visible when describing what the review established.
Don't ask people to upload private exports into a public thread. Provide an invented example and a route for reporting a problem without exposing real customer information.
Update the note when reality disagrees
After release, keep the migration instructions connected to the version they describe. If you discover a missing case, add a dated correction and explain its practical effect.
Return to the public announcement when a correction changes the user's next action. Readers who saved the first post should have a clear route to the current instructions.
Review support reports for misunderstandings as well as defects. A technically correct change can still fail because the instructions assumed a setup that the reader did not have.
Before your next public release, try writing the migration note first. A difficult paragraph often points to a difficult transition. Solving that transition gives you a more useful thing to announce.
Hey I'm Uriel Bitton. I write about building in public strategies and growing startups.
Subscribe for more stories on growing your audience by building in public.
Join us on Buildside: the social network for founders building in public.
Top comments (0)