Skip to content
signalby Travis Loudin

Type to search.

    dispatches /communication / release-notes-in-four-fields

    tipCommunication

    Release notes in four fields

    Write every release note with the same four fields in the same order: what changed, who's affected, what you need to do, where to get help.

    by Travis Loudin
    field-testedplanted

    Write every release note with the same four fields, in the same order: what changed, who’s affected, what you need to do, where to get help. Keep the format fixed so people learn where to look and can skim it.

    The usual release note is a ticket dump. It lists what the team did, in the team’s words, and leaves each reader to work out what it means for them. Expertise makes people worse at predicting what non-experts will understand, and trying to be clearer does not fix that. A template helps. A long, accurate, technical note can also read as a brush-off, even when it was written in good faith.

    The four fields

    Field What goes in it
    What changed The outcome, first, in the reader’s words. If the change takes something away, say so here, before readers discover it themselves.
    Who’s affected The roles or teams, named. If two groups are affected differently, each gets its own short note with only what matters for their role.
    What you need to do The action and the date.
    Where to get help A named person, the one channel requests go through, or office hours.

    How it was built, the root cause and the ticket numbers are an appendix. Link them underneath for the people who want to dig.

    An example

    Before, straight from the tracker:

    FIN-482  Resolve approver from manager field in routing service
    FIN-377  Remove approver dropdown from submit form
    FIN-490  Backfill approver on open drafts

    After:

    Expense reports now go straight to your manager
    
    What changed
    From Monday, an expense report goes to your manager for approval as soon
    as you submit it. The approver list on the submit screen is gone, so you
    can no longer send a report to someone else.
    
    Who's affected
    Everyone who submits or approves expense reports. Reports you have
    already submitted are not affected.
    
    What you need to do
    Before Monday, open your profile and check that the manager shown is
    correct. If it is not, tell the finance systems team.
    
    Where to get help
    Post in the finance systems channel, or come to office hours on Thursday
    at 2pm.

    The same three tickets are behind both versions. The second one starts with the outcome, names the thing people are losing, and gives one action with a date.

    Sending it

    • For a change that affects how people work, send the first note no later than two weeks ahead, then send it again. Repeating it feels excessive to the team that has lived with the change for a month. For the reader it is new every time.
    • One post in one channel reaches a fraction of the people who need it. Plan on more than one channel and more than one pass.
    • Put the note in the definition of done, so it is built into the release instead of added afterwards.

    ← More in Communication