This post is about communication patterns in software projects. For your organisation and its teams to be truly agile and effective you should build a communication system.
- Keeping people focused, aligned and effective
- Sharing information in the right places
- Optimising incident response times
- Operational safety
Your organisation is spending vast resources to optimise various parts of the technical infrastructure to help your developers work better. We all spend a fair amount of time communicating and the quality of the deliverable result of our work is largely affected by the accuracy and completeness of such communication.
As your organisation grows to employ people from an assortment of cultures and beliefs, having a few guidelines on communication can improve cohesion and relieves the stress of having to guess how a person or team expects to receive information.
I’m keeping notes, trying to build a toolkit as I see that communication is key to the execution of a project regardless of the team’s size.
Who's this post for?
Should you read this post, or spend your very precious time doing what makes you feel productive?
Well, building a communication system, sounds like a manager's work, but in reality requires collective effort.
Let's surface a couple of Andy Grove‘s quotes:
The output of a manager is the output of the organizational units under his or her supervision or influence.
A team will perform well only if peak performance is elicited from the individuals in it.
I'm arguing that no matter if you are a designer / developer / tech lead or manager, helping to build such a system is a step to augment the output of the team.
Adding developers to a project rises work done linearly, but the complexity and communication costs rise at the square of the number of developers.
– Brooks's Law
How to deal with communication complexity? Devise rules according to your organisation’s needs and get people to follow them. Do document, using templates and ceremonies which are essential to have an organisation run as a well-oiled machine.
Should you improvise and author your own peculiar rules? Probably not, there are vast resources online and you can graft whatever you consider applicable.
The most important thing, especially for early stage projects, is goal-setting. Use a framework like OKR.
An OBJECTIVE, is simply WHAT is to be achieved, no more and no less. By definition, objectives are significant, concrete, action oriented, and (ideally) inspirational. When properly designed and deployed, they’re a vaccine against fuzzy thinking—and fuzzy execution.
KEY RESULTS benchmark and monitor HOW we get to the objective. Effective KRs are specific and time-bound, aggressive yet realistic. Most of all, they are measurable and verifiable.
For more information about OKR, start by reading Measure What Matters from their inventor John Doerr. A great example of OKRs out in public, is Gitlab's ones.
For software projects, I can identify various types of communication media to be used by team members. This post covers the following:
- Project Management Application
- Realtime Conversation Application
- Wiki / Documentation
1. Pick a Project Management Application
Jira, Trello, Asana, Phabricator, pick one, then make sure people know how to interact with it. I bet you work with very smart people, but for such integral processes you should have a short manual so that they are feel comfortable with it.
Common questions you can consider answering:
Who creates tickets / tasks / cards and when?
This can be a tech lead, a product owner / project manager, or any team member as long as their guided and conform to the set conventions.
What is the structure of a ticket?
A ticket can have the following format:
This section is about determining the goal of this ticket. What problem does it solve?
What are the constraints which must not be violated?
This is where all the necessary technical information should be placed. It can be short or very extensive depending on the complexity of the task. You may create subtasks for authoring of design documents based on which the actual implementation will take place.
What are the required steps for a ticket to be considered done?
The definition of done is commonly confused with moving a ticket to a column named “done” in a kanban app. The deliverable of a ticket and the scenarios which have to be satisfied must be clearly mentioned in the ticket. Nobody should pick up and waste time on a ticket which has not been fully specced out. If you anticipate follow up actions or measures, after for example the technical implementation of a ticket has gone live, document them to ensure those actions are taken on time.
How long should I wait to get an answer on a ticket comment I left?
This is a tricky one, but I'd say at most a day. It is tricky because we set it any lower we're risking sacrificing focus by having people to constantly looking at their inbox.
2. Realtime Chat Application
This can be an application like Slack, irc, rocket chat, or other.
Let's focus on what all the cool kids are using these days; Slack.
One thing you should definitely try is to convince people not to use DMs. You cannot forbid them completely, but they don't scale that well and it is yet another place where office politics might be brewing.
When to say something on Slack?
Use it for volatile information or emergencies. One should not feel obliged to read every message in any of the numerous channels being invited.
When to use @here and @channel
@here notifies members of a channel who are currently active in Slack. @channel notifies all members of a channel, whether they are active or away.
As documented in the Slack guides, you should use them sparingly. If people are abusing them, remind them and get them to conform.
Name them based on a pattern.
- Prefix channels meant to be joined by developers, with
dev-, for example
dev-elixir. This will let people form tech guilds, where they can more easily tap into the specific technical domain without creating noise in other channels.
- Prefix team-specific channels with
team-, for example
- You may have a few channels dedicated for support. Prefix them with
support-, depending the group from which one would want to get support from. Define rules on what qualifies as support. A good rule of thumb is “if it will take more than 30 minutes or if you can do it yourself then it’s not Support”.
- Always set a topic mentioning the scope of the channel and its rules. If for example it's a team-specific page, have a link to a documentation page with info about the team.
As silly as it sounds, emojis are surprisingly important in how people communicate. It's very hard for most folks to indicate emotions over text and emojis help support that. They've also been an effective way to communicate better across language barriers.
Let’s admit it, emojis are fun. Work can be fun too. Sprinkling emojis all over your messages on slack at work won’t make work fun though. There are ways to enjoy make yourself enjoy work more, or find the right employment to maximize your happiness. That's way beyond the scope of this post though 🤐.
zorbash> :shipit: We’re releasing the much expected feature of anti-anti-gravity to all our new car models.
Avoid using emojis in design documents and release-specific documents (release coordination docs, changelogs) or any document which might be read during some firefighting process.
Avoid using them in commit messages. They’re meant to be succinct, unambiguous and above all greppable.
For the love of god, you wouldn’t want someone looking for a memory leak fix to have to search using
When in doubt, don't use an emoji.
This section isn't about concurrency primitives. I'm talking about Slack threads. They are ideal when you wish to ask a question, or have a quick discussion, keeping it contained. Why would you want to contain it? Because for people not involved, it’s noise. You'd be right to wonder if there's ever any escape from noise in the modern workplace anyway? reference
zorbash> Good people of #support-devops, I just discovered that the X-Strict-Allow-Kittens header is included twice in all our responses. Is there any chance this is intended? (thread)
When you start a question thread and it gets a conclusive working answer, if possible edit the head message of the thread with a
[resolved] tag, so that others know you no longer need help and they don’t have to react and read it. You may also use an emoji like ✅.
zorbash> I think we should implement FEAT-1337 of underwater balloons on Mars using a blockchain, wdyt? (thread) the_m4rtian> What about planting potatoes instead? jennyfromtheblockchain> Check out this new crypto, the potatocoin, might me useful.
In this case, given that a ticket for
FEAT-1337 already exists, the discussion should take place on the ticket or any design document associated with it. Ideally for a non-trivial feature or product, opt to arrange a design review meeting with the team.
Product development is inherently asynchronous these days, when you take into account remote people and that it takes big chunks of time. Using a realtime medium does more harm that good. Don't do product development by talking on slack threads.
Sometimes it's better to schedule a meeting instead of breaking people's focus and making them watch a thread. To aid you in such a decision, consider reading this previous post about effective meetings.
Is it OK to add bots to channels? Maybe. Ideally bots should have their own channels, not for them to chat with each other of course 😛. For example you may have channels for #releases and #project-x-ci. Prefer setting up bots to notify the minimum number of relevant people directly instead of sending messages to public threads.
Use chatops to help complete otherwise tedious tasks like creating a support ticket for a specific team. Or to answer a question for when did the last deployment of some service take place.
Have a bot flood a channel with application exceptions.
In my experience I've seen many times secrets being shared in places where they shouldn't. Even seemingly harmless information like
wifi password or
the door code can be used at least for social engineering purposes.
Using encryption should be the go-to option sensitive for information and thankfully there are options like keybase making it easy even for non-tech savvy people.
3. Wikis / Documentation
- Each code repository should clearly mention its code owners. Which team / person should be contacted when there's an incident? How are incidents meant to be handled?
- For issues where people keep using Slack to get support, consider creating playbooks
- Each repository should use pull request templates (see github, gitlab)
- What is the outline of the strategy of the organisation / team?
- Have an technical onboarding document per team
- Have a top-level diagram of tech architecture and fundamental business processes
- Document release policies, planning and coordination
- Build or adopt a methodology for secure software development. See: OWASP - S-SDLC
- Have a postmortem template. This one from google can serve as an example
Document the structure of the organisation, the teams that there is. Author a page for each one of them and let the team be responsible to keep it up-to-date.
A template for a team page can be the following:
List areas you are responsible for. Services you own. Be specific and add links.
How We Measure Success
Define the KPIs (key performance indicators) of the team. Ideally have a dashboard displaying those KPIs and add a link to access it.
Add a links to any goal-setting application or documents.
- Standup at 10:00
- We work in 2 week long sprints.
- Backlog grooming: 1st monday of the spring
- Sprint planning: X day of the month.
- Team retrospective: Last friday of the sprint
- Team lunch every other friday at 12:00
- We buy a plush toy mascot every 2 months
List all the members of the team, names, usernames and photos. Add a link to a calendar with members’ holidays.
List and explain any common team specific terms which you deem useful for cross-team collaboration and onboarding.
- When Coffee and Kale Compete by Alan Klement
- Top Takeways from Andy Grove's “High Output Management”
- Gitlab's Communication Handbook
- A list of postmortems by Dan Luu
All the reading resources above are also available as a list on Tefter.