The 10 Commandments of Team Communication
When you start your company and you have to deliver a product very quickly to assess market fit you can excuse yourself for being sloppy. The aim at that stage is reckless speed and raw experimentation so you can quickly assess the viability of the product you are creating and change on the fly fast — there is no time to spend making everything pretty and perfect — a skeleton product will do. At that time you are often a very small team where everyone knows each other well and constantly communicates the work they are doing, so sensible communication practices can be excused.
But as your company grows, this modus operandi does not scale and communication starts becoming a big problem. As more people join the company and more teams are created, typical solutions are (sometimes without being well understood) applied to improve the communication structures. These often include wiki spaces, standups, meetings, and more meetings shaped like guilds and more standups, sometimes with other teams, retros, refinements, catchups… it never ends.
These are all good efforts and occasionally they can bear good fruits, but communication is not about how much you talk but how well you talk and how effectively your work speaks for you. You can tell your wife you love her a million times but a rose will often make her day better than anything you may say. And while roses may not make team communication any better, a job well done will; a well written README file, a concise code base, a file structure that makes sense, etc. All of these are what’s required in order for us to scale the ever mounting complexity sensibly and transfer this knowledge in meaningful ways.
Commandment is Tongue in Cheek
The DevOps culture that has swept across the tech world by storm encourages teams and individuals to be more autonomous and to be proactive in finding solutions and applying improvements. However being autonomous does not mean do whatever you want and/or however you want. You have a responsibility to your team and to the entire company to do work that’s easy to understand and that anyone will be able to grab from you and work with it in a short amount of time without needing you there for the most part.
I am not a big fan of rules and rigorous processes because this makes it feel as if you are part of a bureaucratic organisation where creative output is restrained by these very same rules that are trying to impose order, but if you are given the freedom to do great work it bears upon you to act as judiciously as possible and to create work you can be proud of so that these rules don’t need to be imposed, and instead you have guidelines that you can constantly improve upon.
Therefore the word commandment is tongue in cheek, I don’t like dogma and you shouldn’t feel compelled to follow any rule without giving it a good amount of thought, but I hope this helps you in your work and your organisation.
The overall objective of these commandments is to minimise the cost of context switching so your engineers can reach flow much faster.
If the work that your engineering teams produce is poor and confusing, then the amount of time they are going to take to learn something new is going to escalate out of proportion, costing your organisation thousands of engineering time and increasing the amount of technical debt and poor software.
1) You shall understand who your “customers” are
One of the things I’ve learned from value stream mapping is that your most immediate customer is the next step in the value stream, so one of your main concerns should always be to cater to that customer, just as much as the end customer! Let’s say for example you work in backend and you create an application that the frontend makes heavy use of, your aim is to make it as easy as possible for the frontend to do their job efficiently, that includes for them to be able to test thoroughly and efficiently and to listen to any requirements they may have and cater to fulfil those as well as possible. So following this logic, devops people should cater to create services that make developers life easy and developers should create applications that operations people can run easily and efficiently.
Take the time to understand your immediate customers, speak to them more often, organise meetings, understand each other, work together and cater to them better.
In this entire document customer refers to whoever uses your application outside of your team.
2) You shall create every repository as if you are going to open source it
Always create and maintain your code as if millions of people were watching you and laughing at you for creating something messy; feel ashamed of messy and complicated code and crappy documentation — aim to always create work you can be proud of.
It is too normal for developers to cobble something up that just works and easily be happy with that. The problem with code that “just works” or is hacky or lacks elegant, concise documentation is that not only it creates technical debt, it creates tens of wasted hours by whoever struggles to understand your work. So next time you feel you don’t have the time to create something with finesse, don’t just think about your time, think about the time you are wasting the entire company and how costly that will be!
There is no saving money or time when it comes to poor code, poor code is very costly, much more so than good code.
3) You shall aim for coding simplicity
Great code speaks simply.
Great code yields simple running and execution procedures for operations or anyone else using it.
Great code yields simple documentation. If your documentation is overcomplicated or a pain to write, it’s may very well be because your code is not so good and can be simplified, so if that’s the case, simplify your code first, so you can write an elegant README.md file. (This paragraph also applies to automation)
Your code should be very easy to read and understand. I know that sometimes you may be very tempted to show off your awk or complex regex skills, but if there is a simpler command that can achieve the same thing without significant performance penalties and it’s easier to read, always aim for that option. In fact, any time your code looks complicated or ugly step and think hard how to make it more simple. There is beauty in code that’s simple to read and easy to understand, when code is well written, even a person who is not familiar with the language can pick the general idea of what you are trying to do and you will save the entire company a lot of time.
Of course, sometimes it is not possible to do something elegant, beautiful and simple, in that case make sure you add comments where you explain why this was done this way, and try to at least arrange code in concise blocks where it’s easy to read.
Make sure to comment “hacky” solutions especially; if there was absolutely no way to do it any other way at the time, explain why, and aim to fix it in the future.
4) Kondo your file structures
Marie Kondo’s philosophy on house decluttering is simple; only keep stuff that “sparks joy”. While files may not spark joy, you should not keep anything that doesn’t serve a specific purpose, if it’s not needed, get rid of it, the more redundant files and folders you leave in a repo, the more someone will have to struggle to understand the utility of them.
I’ve worked with many people that create file structures of their repositories like my mother arranges her kitchen; so only she understands the logic and locations of all her utensils and ingredients. This often tends to happen because someone was trying to figure stuff out, then they found out how to do it, but they just decided to leave it as it was, without cleaning up all the trials and errors, or simplify the complexity of their initial divagations.
It is normal to have a little chaos in your repositories when you are starting to work on something, but as your work matures, improve it so it makes logical sense — REMEMBER, your work is not just for you to see! Try and arrange folders and files so that it is as intuitive as possible, and if you feel it needs some explaining, add an explanation on the README.md file.
5) You shall have a decent understanding of what you are doing
I know this seems very obvious, but I worked in places where people are looking for a quick solution to a problem, they find some code in stackoverflow and paste it there without fully understanding it — or they paste someone else’s work without giving it a second thought. Sometimes this code may be complicated, uncommented and no one knows what it does.
One egregious case of this can be found in nginx and apache config files. I’ve worked with some of these files that made absolutely no sense to anyone in the company and no one had the guts to remove or simplify them in case something broke.
So try to understand and add comments to your code or configuration, and wherever possible put a link to the source in the code so people can at least see where you got the idea from, and put a link to the ticket or original reason why doing that, in case it’s not needed any longer.
6) You shall document contextually, rather than comprehensively.
When the agile manifesto says “Working software over comprehensive documentation”, they don’t necessarily mean no documentation at all.
You don’t need to document all day like a maniac to create elegant and useful documentation - and you shouldn’t. If your documentation is too exhaustive, let’s say like a man page, sometimes it can have the opposite effect of confusing and overwhelming whoever needs to use it.
Don’t get me wrong, exhaustive documents like man pages are fine as a form of reference, but for someone who is new to the application they don’t offer a lot of context and usually very few examples, so it is not the best form of document to get started. The same way you generally don’t give someone a dictionary to learn a new language. Instead of exhaustive or comprehensive documentation, offer contextual documentation instead.
Contextual documentation aims to provide all the necessary information required for someone to understand, operate and diagnose the application down the value stream. The why, when, who, what and how; prerequisites, examples, how to test your app — anything that you need to get started.
If when you are documenting you start to realise that it is too complicated and it takes too long to explain someone how to use it and give context, ask yourself if the design decisions you made or the work you have done so far is incomplete. Good software should be easy to use and as intuitive as possible. If your documentation is too complicated, it could be because your software is not as simple as it should be.
Always ask your colleagues and other teams if your documentation makes sense and improve upon it if needed. The aim is that they don’t need to ask you questions and they can easily work it out by themselves.
7) You shall keep contextual documentation close to your source.
There seems to be a trend going on in many companies about confluencing everything, this is by no means a bad practice in itself. However if that means separating documentation from the repository, I see two problems with this approach:
- You have to effectively maintain two sources of truth.
- You have to trust that your customer knows where this confluence page is, and that she has access to it and doesn’t forget to go look at it when working with your application.
Having everything in one place makes things simple for you and your customer. I would advice using confluence to reference the repository, add a description for what it does and a link to the REAME.md for further documentation.
Use a wiki to maintain general documentation that applies to multiple repos, or perhaps tutorials with images that are better shown there, but then provide links to the README.md file in your repo where more up to date information is provided. It will be easier for you to keep your README.md file up to date with details.
You can also use the wiki to create documents about engineering practices, coding styles, etc. That you can later link on your README.md files.
8) You shall write concise and easily understood tickets
When you write a ticket for your own team, or for another team or even for yourself try and provide concise and clear details. Every ticket should have context, action items and any additional information that you can think of.
Here are a couple examples of most common bad tickets:
- One liner, vague tickets that explain nothing and give no context. Something like “Create role for x” or “give root access for y” is not a good ticket. Instead provide context why this is required, what needs to be done and any additional information that will help whoever needs to work with it.
- Tickets that contain way too much information. Examples of this are just pasting a chain of emails so the person who needs to do the work has to go through the whole exchange and try to make sense of it. This is especially bad when the person is not even familiar with the topic.
9) You shall ensure that all members of your team understand these and other best practices
It is not enough that you alone are great at producing outstanding work if you have to work tirelessly to fix the work of others, sometimes it is better to take a step back and have discussions with team members or other codependent teams and address these issues and define clearly an efficiently what it means to produce great work and how to achieve it, draw some guidelines and share them with your team and with the company at large — discuss them and most importantly, commit to follow them!
10) You shall take your time to do great work.
Make sure to take your time to do a good job, if a product owner or anyone else tries to push you to deliver quicker, try and find a compromise, explain that good things take time, and it creates a lot more value down the line for you to spend the time doing an excellent, well understood application than having to pick up the pieces later. Agile doesn’t mean breakneck development, it means fast, short iterations of good quality software following design principles that aim for quality. Ironically if you take more time now, generally you and the company will fly down the line, so keep that in mind.