How to Document a Breaking Configuration Change

The Slack message comes in on a Tuesday. Engineering is shipping a breaking configuration change next week. It affects every customer. There is no migration guide yet. There is no announcement draft. Nobody has told support. The question of who is supposed to write the docs has not been answered, and the question of what to write has not been asked.

Most teams treat this as a documentation problem, when it is really a coordination problem with a documentation symptom.

The workflow for handling it is not complicated. Most organizations skip the first step, which causes every other step to fail.

Draft the Announcement Before Anything Else

The most common mistake is treating the release note as an afterthought. A developer writes a quick summary right before merge. Support gets a Slack message the morning of the release. Customers find out when something breaks.

The announcement is the most important piece of writing for this release. It sets the tone for the entire migration. It is what customers read first, and it is what they will quote back to you when they open a support ticket.

Draft it first. Before the migration guide. Before the changelog entry. Before anything else.

The announcement needs to answer three questions clearly: what is changing, why it is changing, and what the customer needs to do. If the change is required for security reasons, say so. If it fixes a performance problem that has been degrading the platform, say that. Customers are more forgiving of migrations when they understand the trade-off. What they do not forgive is finding out about a breaking change from an error message.

Be specific about timing. "We plan to deprecate this pattern in a future release" is a way of avoiding commitment, not a timeline. GitHub's stated policy is that any API version is supported for at least 24 months after a newer version ships, with exact sunset dates published in the documentation. Stripe pins each account to the API version active at creation, so existing integrations never break silently. Both approaches are documented in API versioning strategy breakdowns alongside Postman's 2025 State of the API data. The standard for enterprise APIs is a 6-month announcement period, 12 months of active migration support, and 18-24 months total before removal, per Redocly's versioning best practices. Your timeline does not need to match those exactly, but it needs to exist and it needs to be published.

The announcement also needs to classify the change. Is it breaking or non-breaking? Opt-in or automatic? Reversible if something goes wrong? Semantic versioning exists precisely to communicate this, though Postman's 2025 State of the API Report found that only 26% of teams actually use it, even among the 60% who version their APIs at all. The gap between intent and discipline is where production incidents live. Classify the change explicitly in the announcement, even if you do not use formal versioning.

The Part Where Most Organizations Fall Apart

In most companies, a breaking change exposes a coordination gap. Engineering wrote the code and considers its job done. Product management assumes technical writing will handle the docs. Technical writing is waiting for the spec. Support does not know the change is happening until customers start asking questions.

The result is conflicting information, last-minute scrambles, and documentation that publishes after customers are already frustrated.

Clear ownership is the fix. One person who is accountable for the entire communication rollout: the announcement, the migration guide, the support briefing, and the post-release monitoring. In most organizations, this is a Product Manager or a senior Technical Documentation Lead. The specific title matters less than the clarity of the assignment.

That person's job is to ensure the engineering team provides the technical details early, the announcement is drafted and reviewed before it goes to customers, the migration guide is accurate and published before the change ships, and the support team is briefed with the same information customers will receive plus the internal context they need to triage edge cases.

That last point is worth dwelling on. Support enablement is not a nice-to-have. When the support team is caught off guard by a breaking change, they learn about it from angry customers, which means they are already behind when they start responding. Research on support enablement is consistent: "Support enablement allows the support team to weigh in on the launch and this often leads to new information that helps the product team really hit the mark." The support team often knows how customers will react before the product team does. Bringing them in before the announcement goes out is both a quality check and an early warning system.

The channel strategy matters too. Email for high-impact changes. In-app banners for customers who need to take action before a deadline. Changelog for the record. Knowledge base article for the detailed migration steps. These are not interchangeable. A changelog entry alone is not sufficient notice for a breaking change. Proactive communication before a change ships can cut inbound inquiry volume by 25-40% on average. The reduction comes from informing customers before they encounter the problem, not from better documentation after the fact.

What Good Migration Docs Actually Look Like

The migration guide is where most technical writing goes wrong. The writer knows the system well, so they explain the architecture, describe the rationale, and cover every edge case in sequence. The reader, who is already annoyed that they have to do this work at all, gives up somewhere around paragraph three.

Write for the annoyed reader. They had a working integration. You are making them do extra work. They want to know what to change and how to verify it worked. That is the entire job of the migration guide.

Put the most common migration path at the top. Use code blocks that show the before and after states explicitly. Pull edge cases into separate sections so they do not clutter the main path. If 5% of customers have a non-standard configuration that requires a different migration, that is a separate section at the bottom, not a set of caveats woven through the main instructions.

If both the old and new configurations will coexist for a period, the documentation needs to explain which one to use and why, without creating decision paralysis. The documentation should also make clear what happens if a customer does not migrate by the deadline, framed as information rather than a threat. Customers who understand the consequences of inaction are more likely to act.

Tom Johnson's release process guide makes a useful point here: release notes are meant to be short teasers for content elaborated in the documentation pages, and a good release notes page will have many "For more information, see..." links. The announcement and the migration guide are different documents serving different purposes. The announcement creates urgency and context. The migration guide provides the steps. Neither should try to do the other's job.

After the Change Ships, the Work Is Not Done

The documentation is not finished when the release goes live. It is finished when customers can successfully migrate without opening a support ticket.

Monitor the support queue in the first 48 hours. If the same question appears five times, the documentation did not answer it. Update the guide immediately. The documentation should evolve as you learn how customers are actually experiencing the migration, not six months later during a content audit.

A product feedback loop, as LaunchDarkly describes it, is "a systematic process for collecting, analyzing, implementing, and following up on user feedback to continuously improve your software." The same principle applies to documentation. Collect the signal from support tickets. Analyze where customers are getting stuck. Update the content. Measure whether the ticket volume drops.

This is also how you catch the behavioral changes that are harder to document than syntactic ones. A study by Ochoa et al. found that 21.9% of breaking changes in Maven Central were not documented at all. The ones that get missed are usually behavioral: the method signature stays the same, but the output changes in a way that breaks downstream assumptions. Post-release monitoring is the only reliable way to catch these, because customers will find them even when the documentation missed them.

The teams that handle breaking changes well are not the ones with the most process. They are the ones who treat documentation as part of the engineering workflow, not something that happens after the code is merged. The announcement gets drafted before the migration guide. The support team gets briefed before the customers. The docs get updated when the tickets reveal gaps.

Doc Holiday generates structured release notes and configuration change documentation directly from engineering workflows, then provides a validation layer for a technical writer or support lead to review, refine, and publish under deadline pressure. For lean teams that need to move fast on high-stakes communication without creating process debt, that is the difference between a controlled release and a fire drill.