Write status updates that help someone decide
Turn a list of engineering activity into a short update that explains what changed, what remains uncertain, and what decision or action is needed.
Write a status update around the reader's next decision: what changed, what that means for the commitment, what remains uncertain, and what action you need from whom. Keep supporting detail available without making the reader search for the point.
'Worked on the import' reports activity. 'The import works for valid files; duplicate handling still needs a decision before release' tells the reader what is ready and what must happen next.
A project update is not a diary of how hard you worked. Its reader may need to decide whether to change a date, answer a product question, provide help, or simply leave the plan alone. Put that decision ahead of the chronology of your week.
Choose the question your reader needs answered
Before writing, name the reader and the decision they can make. A teammate may need a precise technical observation. A product owner may need to choose behaviour. A manager may need to resolve a priority conflict. Sending the same long update to all three can leave each person searching for a different point.
Todd Rogers and Jessica Lasky-Fink’s Writing for Busy Readers is useful here. The authors’ public principles emphasise making purpose and next steps clear. Applied to engineering updates, this means reducing the work required to understand and respond, not deleting every technical detail.
A status message can have no request. In that case, say what changed and whether the existing commitment still stands. Do not invent a decision merely to fit a template. The structure should follow the reader’s need.
Try the decision
A migration is 70% through and one dependency is uncertain. What belongs in the update?
Activity alone does not tell the reader what decision or help is needed.
Next step: Add the current outcome, uncertainty and next action.
This is an illustrative decision with stated assumptions. It cannot establish your employer’s policy or predict an individual career outcome.
Rewrite an activity report as a decision update
Consider an illustrative draft: “This week I worked on the import feature, updated validation, fixed some tests, and discussed edge cases. I will continue next week.” It may be accurate, but the reader cannot tell whether the feature is usable or whether anyone needs to act.
A more useful version is: “The import now accepts the agreed valid-file examples and rejects missing required fields. Duplicate records still have no agreed behaviour. I need the product owner to choose whether to reject the whole file or report individual duplicates before I can complete that case. The release date remains provisional until this is decided. Test results and the two examples are linked below.”
The revision names a result, a remaining uncertainty, a decision owner, and a consequence. It does not claim the feature is finished because a subset of tests passes. It also avoids treating a product question as if the developer could solve it by coding harder.
For an update without a blocker, explain the result and the next boundary: “The agreed cases pass in the test environment. Review is scheduled; release approval is still pending.” The guide to end-to-end ownership explains why implementation, review, and release are separate responsibilities.
Keep uncertainty and evidence visible
Use precise states. “Implemented” is not “reviewed.” “The test passed” is not “all requirements are covered.” “A date looks plausible” is not “the team has committed to it.” An update becomes less useful when the wording makes the situation look more certain than the evidence supports.
When an estimate changes, explain the new information and its consequence. Do not conceal the change in a long list of completed tasks. Link to the supporting issue, example, or test result that the recipient is permitted to access. A link should help verify a claim, not merely create the appearance of documentation.
If a check could not run, say that. If an external dependency is unconfirmed, say who is following up. The explanation of estimation uncertainty is useful when the update concerns a date rather than a completed result.
Keep confidential details in the appropriate system. A broadly distributed status note may need a bounded description rather than a raw log or private customer example. Clear communication does not require spreading information beyond its intended audience.
Make the requested action easy to take
Name the action, the person or role that can take it, and any meaningful deadline. Include the minimum context needed to answer. “Please advise” is vague. “Please choose between these two behaviours; the examples show what the user receives in each case” makes the decision concrete.
Where you have a recommendation, state it and explain the decisive reason. Do not hand over an unstructured pile of options when part of your responsibility is to analyse them. Equally, do not manufacture authority by presenting your preferred choice as already agreed.
If the requested decision affects several teams, point to the existing discussion or decision document. Avoid creating parallel approval paths in private messages. A readable design document can hold the fuller reasoning while the update identifies the decision now needed.
Avoid turning updates into a second job
Reuse the actual state of the work rather than maintaining a separate optimistic narrative. Agree a cadence and channel that suit the team. A short message when a meaningful condition changes may be more useful than a daily wall of text with no new information.
Do not measure an update by its apparent confidence, length, or number of achievements. Test it by asking whether the intended reader can identify the state of the commitment and the next action. If not, move the missing point forward.
The best closing may be one sentence: “No decision is needed; the next update will follow review.” Or it may be a specific request. In both cases, the reader should know what happens after they stop reading.