Permanent channels
You often hear people say that the only constant in product development is change. It's a catchy phrase and it paints a good picture of the everyday life of product development. But it fails to tell the whole story: most of the day-to-day work changes slowly.
We work on different things all the time, so change feels constant. But the way we work doesn't change as fast. In fact, no matter how fast you ship changes to your product, you don't change how you onboard new team members or operate your servers as often.
The goal of permanent channels is to communicate what changes slowly in a team. In most teams I've been part of, there was no form of communication covering those aspects; they got lost in the sea of little things that change all the time. What you choose to document or not says a lot about your culture, it shows the focus of your engineering management style. Permanent channels tell your teams what really matters to you.
Often information that belongs to a permanent channel gets easily lost in a volatile one. A good example is architectural decisions. We spend a great deal of time discussing code changes; improving our systems is an important part of the job. Sometimes discussing a code change in a pull request ends up being a conversation about the architecture of some system. You should not have that conversation in a pull request: you want to store how architectural decisions are taken because people without enough context need to go back to that decision to understand their present. If you need to store the outcome of a discussion, then a pull request isn't a good media: you close pull requests once the code is merged and you can't easily tie them to the big picture. You need a better-fitting channel.
These mix-ups of volatile and permanent channels occur every day and there is no way you can control the outcome of all these conversations. Keep in mind that code reviews is just one example, there is much more. Policing conversations doesn't scale and sends a message of distrust to the teams, so crafting permanent channels and helping teams use them is central to the role that leaders have in building communication infrastructure.
Let's go over some examples.
Developer book
Permanent channels give team members points of reference. You can think of the information in these channels as tools to help people navigate the complex aspects of their job. If someone is unsure about how to approach a problem, they have some information as a starting point.
A developer book is the simplest and most effective permanent channel. A developer book is a document that provides at least the following information:
- How to onboard new team members
- How we work
- How we operate
- How to offboard team members
I use this list as a table of contents for a first draft of this document. In order to explain how to use a developer book, let me run the communication debugger one more time:
-
Do we need to store the information we share via this channel?
This document is a permanent channel, so the answer is obviously yes. You need to store the data for long-term consumption. People must be able to use the document as a reference guide, so it's vital that the document is available at any point in time.
-
How relevant is contextual understanding?
No contextual understanding is a strict requirement. The point of the document is to remove implicit knowledge from within teams. You can think of the document as a map: if the information isn't clear, people get lost.
-
What's a good media for this channel?
I suggest you store it where you store your code. Here is why: when I wrote such a document for the first time, I was afraid that people wouldn't read it, adopt it, or use it. I spent a great deal of time trying to find a way to ensure the success of the initiative. I came up with an approach that I find beautiful in its simplicity: I asked my teams to discuss changes to our processes via a pull-request to the repository of the developer book. The document became the point of reference for every discussion about the activities that don't involve coding. It happened fast because the workflow was familiar. When we agreed to change something, we merged the pull request and the doc was always up-to-date.
The table of contents I provided is just an example. I didn't try to be specific by design. Different companies have different needs. Good examples of topics you may want to cover in the document are:
- Diagrams (sequences, architecture)
- Incident management
- Reference readings
The only requirements are slow-pace change and, as always, people's needs for information.
Internal blog
As your teams scale, sharing knowledge becomes more and more important. You want to avoid that different teams solve the same problem multiple times. A great way of sharing knowledge is to write about what you learned in an internal blog.
Fostering a writing culture helps your teams in many ways:
- Becoming a better writer helps becoming a better developer, too.
- People can proudly share their achievements and simultaneously help other team members learn something new.
Let me examine the characteristics of the channel using the communication debugger:
-
Do we need to store the information we share via this channel?
It's necessary to store this data for long-term consumption. Blog posts are often long reads, so people need a way to read them when they have time. Archives are a nice feature too when you are thinking about past experiences.
-
How relevant is contextual understanding?
A bit of contextual understanding should be the norm for blog posts. It's OK to make some assumptions about the audience. It's not OK to assume the reader knows everything about the content because that defeats the purpose of sharing knowledge.
-
What's a good media for this channel?
Whatever blog system your teams are comfortable with.
You may be wondering what the right topics for blog posts are. A good answer is whatever people feel like sharing. Avoid policing content: people must be free to share what they think is important to share. It only works if people use an internal blog as an actual blog.
A nice side-effect: internal blogging makes public blogging much easier. The delta between "something we wrote for ourselves" and "something we want to share with the world" is often small. A public blog is a great marketing activity, it helps with hiring and improves the mood of your teams. It can feel great to share what you're doing with the rest of the world.