A release can go exactly to plan and still be labelled a failure. The deployment finishes on time, the dashboards stay green, and yet the product owner is irritated, support is flooded and the finance lead wants to know why the new model “is not working yet”. When we trace these episodes back, the fault is rarely in the code. It sits in the distance between what people assumed a release would deliver and what it actually delivered. This article diagnoses that gap and proposes a short remedy: release expectations written down and shared before anything ships.

Symptom: green systems, unhappy stakeholders

You can spot this quickly if you know where to look. Technical health indicators report success, but the conversations afterwards are about disappointment. Common phrasings include “I thought it would be live for everyone”, “nobody said the first week would be noisy” and “we expected the savings immediately”. None of these are complaints about quality. They are complaints about surprise.

In operations work that involves machine-assisted analysis, the surprise is amplified. Models need time to learn normal behaviour, thresholds need tuning, and early output is often rougher than the demo suggested. People who saw a polished demonstration reasonably expect polish on day one.

Differential diagnosis: where the gap actually opens

Before prescribing anything, separate the possible causes. In our experience four of them account for most of the cases.

1. Timing assumptions. Stakeholders picture a single switch-on moment, while the team plans a phased rollout with a stabilisation period.
2. Scope assumptions. Someone believes a feature is included because it was mentioned in a meeting, although it was never planned for this release.
3. Effort assumptions. Business teams expect the release to need nothing from them, when in fact they must review early results, label examples or approve changes.
4. Outcome assumptions. The expected benefit is measured by a different yardstick than the one the team will report against.

Each of these is a communication fault, and each can be spotted by asking one question of three different stakeholders: “What do you expect to be different on Monday morning?” If the three answers do not match, you have found your gap before it has cost anyone anything.

Root cause: expectations fill any silence

People do not wait for information; they manufacture it. When a team is silent about timing, readers assume it will be fast. When a team is silent about limits, readers assume there are none. Silence is therefore not neutral. It is an invitation to imagine the most favourable version of events, and reality will almost always lose that comparison.

That is why a release note written after the fact feels defensive, while the same words written beforehand feel like professionalism. The content is identical. Only the order differs.

Treatment: the expectations note, written before the release

The remedy is deliberately small. Before a release, circulate a half-page note that answers five practical questions in plain wording.

• When will it happen? Give a window, not a promise of a minute, and say what could move it.
• What will you see first? Describe the realistic early picture, including rough edges, so nobody mistakes them for defects.
• What is included and what is not? List the headline capabilities and, just as plainly, a few things people might expect that are not part of this release.
• What do we need from you? Name the reviews, approvals or feedback you will be asking for, and roughly how long each takes.
• When will it be good enough to judge? Agree the point after which complaints are meaningful, so that early noise is not scored as failure.

Notice what the note leaves out. It does not contain architecture diagrams or a defence of design choices. Its readers are deciding how to behave, not whether to admire the work.

A worked example, kept deliberately ordinary

Imagine a platform team rolling out anomaly detection across the services owned by three departments. The old way would be a calendar invitation titled “Go-live” and a congratulatory message afterwards. The new way adds a short note a week earlier.

It says the detection will be switched on in stages over several days, that for the first period alerts will be advisory and will not page anyone, that two named services are out of scope until a later release, and that each department lead is asked to review a short list of flagged events at the end of the first week. It also says that a quiet start is expected, because the system is still learning what normal looks like.

When the first week produces a handful of false flags, nobody is surprised. The department leads have already been told to expect them, and they have already blocked time to review. The same output, delivered without the note, would have triggered a round of escalations.

Measuring whether the treatment worked

You do not need elaborate instrumentation. Two soft measures are enough. First, count the messages after a release that begin with “I did not know” or “I thought”. Second, ask the three stakeholders from earlier to describe the release a week later and compare it with the note. Convergence is the sign of success. If the descriptions still diverge, the note was too long, too technical or sent to the wrong people.

It also helps to review a couple of earlier decisions the team made with similar discipline. Our piece on supporting IT decisions with machine-assisted analysis shows how much easier it is to hold a conversation about results when everyone agrees what the analysis can and cannot say.

Contraindications: when a note is not enough

A note cannot rescue a release whose real behaviour contradicts it. If you promise a stabilisation period and then page people at three in the morning, the document has made things worse. Write only what you intend to honour, and if circumstances change, send a correction quickly rather than hoping nobody noticed. Honest revisions build more trust than silence ever does.

It is also worth being careful about tone. A note stuffed with caveats reads like an insurance policy and teaches readers to skim. Keep it to the facts that change someone’s behaviour.

The same principle outside the server room

The pattern holds well beyond infrastructure. Anyone who has attended a gig, a festival or a community workshop knows how much the experience depends on being told, honestly, about start times, queues, seating and what is not provided. In Bhopal, BhopalOrbit is an events and venues site where organisers publish what they are running and customers find events and buy tickets, which is precisely the setting in which a clear description of what to expect decides whether people leave pleased or irritated.

Follow-up and prevention

Treat the expectations note as part of the release checklist, as routine as a rollback plan. Assign an owner for writing it, give it a deadline in the same week as the freeze, and keep the previous notes in a shared folder so new team members can see how earlier releases were framed. If you are only starting out with machine-assisted operations, the guidance in introducing AIOps to an IT team step by step pairs well with this habit, because early adoption is exactly when expectations run furthest ahead of reality.

Finally, remember the quick diagnostic that started this piece. If three stakeholders describe Monday morning in three different ways, fix the description before you fix anything else. Tell people early, tell them plainly, and the release will be judged on what it is rather than on what someone imagined.