Like many of you, my days are dominated by notifications. Emails from project management systems, source control systems, calendar invitations, ticket updates, and message about messages on other platforms. I’ve noticed that some people use notifications as a power tool, while others seem blind to what happens when they do something. So this post is some tips that I’ve picked up along the way.

The entry level here is to use a correct and meaningful title for the issue/pull request/ticket. I see too many which are just a reference number or two words (and I do edit them if I have write access)! This data is included everywhere, in search results, in notifications – choose your wording well or risk obscurity.

“Report task” vs “Markdown lint and spellcheck results”.

Timing also matters: if I just talked to you about this an hour ago, it’s fine to write a shorter update. But if we’re collaborating on something that’s quite slow-moving and the last update was weeks ago? I’m going to need more context! And most of the time, it’s not much more effort but it does make it much more likely that I’ll take in what you’re asking me to do.

“I agree with the above” vs “I agree that the format option should be added, but not enabled by default”.

If I’ll find out about whatever action you just took by email, then think about how people use email. I don’t have images enabled in email and I’m probably working through my inbox in a triage activity. If you need me to know or do something – make it easier. One of my collaborators completely failed to nerd snipe me into fixing something this week because the examples were supplied as screenshots and I totally missed how fascinating the bug was because I couldn’t see them.

[row of empty image boxes] vs almost anything else. If it’s code or syntax, paste it, not a picture of it! (side benefit, it’ll be in search results)

Your notification should support your intended outcome. If you open a pull request, maybe you want a review for that? It’s on my list if you tagged me but it’s in a crowd there. A pull request that says what is being changed in the title, plus an explanation of why we’re doing it and any particular feedback that’s expected? I’ve got a clear sense of what’s involved, what’s expected and it’ll probably happen because it’s less of an unknown quantity.

“Bug fixes” vs “Add multipath to diagrams, please test on your platform”.

When you send a calendar invite with “follow up as discussed” I have no idea what this is or why I need to reschedule another meeting to attend it. If the meeting is next month I will have even less idea and even if I do attend, there’s no chance that I’ll be well prepared to make good use of the time. But it’s unlikely to survive my calendar contention without more context – and it’s not more words or more work, it’s just more attention while you’re sending the invite.

“Followup sync” vs “Updates and next steps on project supermoon”.

If you’re tagging someone in a conversation that they’re not already participating in, such as on a platform like GitHub or JIRA, they will have no context at all. So “@lornajane, your thoughts?” is just going to sit in my inbox until I run out of things that have the information included with the notification and choose to go digging through some history. You don’t need to replicate the whole conversation but just a note “we’re looking at the options for adding versioning to help with [something I care about], we could use your guidance on how to handle deletions” is enough for me to know how this fits the picture and what you need from me.

Context is everything

The context in which your audience – or audiences – reads what you write is crucial to good communication. I’ve used workplace examples this time, but your open source and community projects follow the same rules. The collaborators who do this well get really, really remarkable results and I think I’m sharing a lot of their secrets here! What are yours? Comment and let the rest of us know, please?