How to Write a Project Update People Can Act On

A project update should tell its reader what changed, what the evidence shows, and what decision or help is needed. “Making progress” asks the reader to guess. “The import handles three sample formats; the fourth is blocked by an undocumented date field, and the data owner needs to confirm its meaning” gives somebody an action.

This guide proposes a short status format for small projects. Its purpose is coordination, not performative reporting. A useful update can be a few sentences when nothing consequential changed, or longer when a decision needs context.

Start with the reader's decision

Before drafting, name who will read the update and what they can do with it. A sponsor may need a scope decision. An operator may need a release window. A teammate may need a review of an example. Put that request near the top with a deadline when timing matters.

Do not disguise an open question as a green status. A milestone can be on schedule while one important assumption remains unresolved. Say both. If the answer is needed before work can continue safely, state the consequence of no response. If work can proceed on another path, say what will continue.

GitLab's communication handbook provides a primary example of using written records to support distributed work. The exact template here is an editorial adaptation: keep decisions and evidence findable for people who read later.

Describe outcomes instead of activity

“Held three meetings” reports effort. “The team chose the smaller migration path and assigned a data check” reports an outcome. Include activity only when it explains a decision or a delay. Link to the detailed artifact rather than duplicating every discussion.

Separate completed, in progress, and unverified claims. A passing build is not the same as a production release. A configuration prepared for deployment is not proof it reached the server. Use verbs that match evidence: drafted, reviewed, tested locally, activated, observed in production.

When sharing a metric, include its scope and comparison point. “Error rate decreased” is not actionable if readers do not know the service, period, or method. If the measurement is uncertain, label it. Avoid adding a number just to make the update look rigorous.

1. Name the reader and the decision they can make.
2. State the most consequential outcome first.
3. Attach the artifact or observation supporting it.
4. List blockers with owner and requested action.
5. Explain the next milestone and its condition.
6. Save the decision and update the note when the answer arrives.

Make blockers specific

A blocker needs a description of the missing input, its owner, and its effect. “Waiting on design” may conceal whether the team needs a layout review, an asset, or a decision between two flows. Name the exact artifact and the latest useful response time.

Keep the tone neutral. The update is a coordination tool, not a place to assign blame. A blocked item can still have useful work around it. Explain which tasks are paused and which proceed. This helps the reader decide whether to intervene or simply keep the current plan.

For remote teams, clarify time zones and dates. “Friday” can be ambiguous across locations and midnight boundaries. An absolute time with a zone makes a requested review easier to schedule. It also makes a later decision record easier to interpret.

A hypothetical release update

Imagine a hypothetical team preparing a search-page release. The update begins: “Candidate build passed local checks for query parsing and empty results. The public release is pending a final accessibility review of keyboard focus.” It then links the candidate revision and review notes.

The requested action names the reviewer and the two pages they need to inspect. The next milestone is conditional: if the review passes, the team can schedule activation; if it finds a blocking issue, the developer will revise and recheck. The note does not call the candidate live or promise a date unsupported by the remaining review.

After the reviewer responds, the owner adds the decision to the same thread and links the final check. This is a hypothetical example, not a report of a real deployment. It demonstrates how an update becomes a record of the decision rather than a stream of disconnected optimistic messages.

Choose a format that survives asynchronous reading

W3C's provenance overview describes information about the entities, activities, and people that produced a result. A status note need not implement a formal provenance model, but linking an artifact and naming who verified it makes claims easier to assess.

Keep subject lines descriptive. “Search release candidate: focus review needed” lets the reader decide where to spend attention. Use stable links to a ticket, document, or revision, and avoid requiring access to a private conversation to understand the current state.

When plans change, say which assumption changed. A new dependency, a failed check, or an approved scope reduction has different implications. Preserve the old decision with a short correction rather than silently editing away the context in which it was made.

Before sending, read the note from the recipient perspective. Could a reviewer tell which decision is theirs and when it is needed? Could an operator distinguish a verified result from a planned check? If the answer is no, move the request and evidence up, and remove background that does not change the next action. A useful update is also easy to revisit: a later reader should see the date, scope, owner, and linked artifact without reconstructing a chat thread.

Project-update checklist

• Put the outcome or decision request first.
• Use verbs that match the evidence.
• Link the artifact behind important claims.
• Name blockers, owners, and deadlines precisely.
• State what proceeds while a blocker remains.
• Include metric scope and comparison when using numbers.
• Use absolute dates and time zones for requests.
• Record the answer in a durable place.