10 Best Practices of Engineering Communication
Improving DevOps communication through words and action
When you start a new company and have to deliver an MVP very quickly to assess market fit, you can excuse yourself for being sloppy. The aim at that stage is raw experimentation to promptly evaluate the viability of the product you are creating and change on the fly fast. At this stage, you are often a small team where everyone knows each other well and constantly communicates.
But as your company grows, this modus operandi does not scale, and communication becomes a big problem. These are ten practices you can use to dramatically improve communication at your company.
The Why
The overall objective of these commandments is to minimise the cost of context switching so your engineers can reach flow much faster. It also means delivering better software faster.
These practices not only benefit your colleagues, they also benefit the future you when you go back to look at your old work.
10 Best Practices of Engineering Communication
1) Treat your colleagues as your customers
Your most important customer is the next step in the value stream, If you are a developer closely working with infrastructure engineers, ensure your work plays well with infra (think 12 factor apps). If you are an ops engineer, ensure that developers have ways to self-service resources and deploy applications.
Ensure that you continuously get the feedback of your colleagues and tweak it to meet their needs and ease their work.
2) Create repositories as if you are going to open-source them
I’ve worked in many places where repos are an absolute mess, with redundant files and code, no READMEs, messy file structure, and even secret tokens. Whenever you create a repo, treat it as if you were to open-source it and think of someone who doesn’t know you or your work; how would they know what this repository is all about?
There is no saving money or time when it comes to poor code.
3) Aim for coding simplicity
Some engineers write overcomplicated code because they feel they come across as cleverer. I even met a couple who thought more lines of code meant more work output.
No, absolutely no. Coding, much like writing, is more elegant, simpler, and easier to understand when written clearly and concisely. I understand the sentiment behind wanting to write more lines of code; if a manager sees only five lines, they may feel you are being lazy. If you work at such a company, I advise packing up and changing jobs. You want to work in an organization that fosters engineering finesse; it’s best for your craft and sanity.
Writing succinct code takes more time and effort. It also goes hand in hand with design; if you hammer away a torrent of code on your keyboard, you are likely not very conscious of the process and will end up handing out a confusing mess to document and automate.
4) Kondo your file structures
Marie Kondo’s philosophy on house decluttering is simple; only keep stuff that “spark joy” and everything tidy and organized. Files may not spark as much joy as possessions, but you shouldn’t keep anything that doesn’t serve a purpose. It is far too common for engineers to goof around with a repository, trying a cornucopia of different solutions to a problem and then leave it all behind when they succeed. This mess makes it exceedingly confusing for those who later find that repository and try to understand its purpose. It’s also much more challenging for the next person to clean your mess because they will need to know what to delete without altering the functionality of your code. Remember that you can recover everything you delete in git, so be merciless with your cleaning!
The file structure is also paramount. I’ve worked with many people who create their repository file structures like my mother arranges her kitchen — she understands where everything goes, but no one else can! A coherent file structure with proper directory names makes understanding much more accessible. Add README.md files to any directory that requires an explanation.
5) Understand what your doing
This point seems rather obvious, but you have no idea how often I’ve come across code where it was rather obvious that the engineer didn’t know what he was doing.
The most egregious example I came across was developers editing NGINX and Apache config files to try and solve issues with their java code, issues that should have probably been solved in code. They pasted config lines from StackOverflow to see if it did the trick; sometimes it did, and sometimes it didn’t do anything, but they always left everything in the file. The result was that I inherited gargantuan config files that no one could understand, and no one dared to edit, fearing it would break something.
Don’t just copy and paste StackOverflow code blindly. Try to understand the code you are pasting, and leave a comment with the source and explanation. ChatGPT and other AI tools will make this issue far worse; if you use tools like this, try getting the AI to explain it first and add the relevant comments!
6) Document contextually, rather than comprehensively.
When the agile manifesto says “Working software over comprehensive documentation”, they don’t necessarily mean no documentation at all. But that doesn’t mean you need to go overboard documenting everything either.
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.
Imagine I give you a list of descriptions of 50 different types of herbs and ingredients in your kitchen — this is exhaustive documentation. Now imagine that I ask you to cook something from that. Are you able to without any previous knowledge? Probably not, but that’s how the documentation of much of the software out there reads (think of man pages)
Instead, it would be more helpful if I give you a few recipes that explain how to use those herbs — that’s contextual documentation. Providing contextual documentation is more valuable to the user and will likely take less time.
If your contextual documentation is bloated and hard to follow, ask yourself the following question, can I design my work to mitigate this? The answer is often yes because confusing and excessive documentation usually veils terrible design.
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 efficiently work it out by themselves.
7) Keep documentation close to the source.
There is a trend in many companies where all documentation goes into Confluence; this is a good practice. However, that often means separating documentation from the repository. I see two problems with this approach:
- You have to 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.
Having everything in one place makes things simple for you and your customer. I suggest using Confluence to reference the repository, add a description of what it does, and a link to the REAME.md for further documentation.
Use a wiki to maintain general documentation that applies to multiple repositories or tutorials with complex formatting, but also provide links to the README.md file in your repo if needed. It will be easier to keep your README.md file updated with details.
Alternatively, you can use any tooling that streamlines this process and keeps documentation handy and centralized while only having to edit it once. The most important takeaway here is that whoever looks at your code should know where the documentation is and have access to it.
8) Write tickets that make sense to your colleagues
When you write a ticket, provide concise and precise details. I often see bad tickets like this:
- One-liner, vague tickets: Something like “Create role for x” or “give root access for y” is not a good ticket.
- Messy tickets with too much redundant information: A common example is 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. Doing so wastes much time for the person who needs to do the job trying to establish context.
Instead, aim for a structure like this:
- Description: Include context and why
- Acceptance Criteria: include accepter too.
- Helpful Sources: Links to sources that may help accomplish the task
- Location of the work: The assignee can fill this when available.
For updates and blockers, use the comments of the ticket. Do this daily if needed.
Writing tickets like this is extremely helpful to get an overview of your board and what everyone is working on. It’s also much easier to see the flow of work and common blockers, doing away with daily standups where information is not recorded, and flow interrupted.
9) Have shared engineering and communication principles
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 or trying to understand their mess, sometimes it is better to take a step back and have discussions with team members or other codependent teams and address these issues early.
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 — and most importantly, commit to follow them!
10) Shift most of the hard work to innovation and elegant design
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, find a compromise, and explain that saving time now, will cost time and money later. Agile doesn’t mean breakneck development; it means fast, short iterations of good-quality software following design principles that save time down the line.
Conclusion
Recently I’ve become quite passionate about platform engineering and the implementation of Internal Developer Platforms because by shifting the philosophy of work to self-service and Developer Experience (DX), all of the principles above become a cardinal goal of development. Still, understanding the principles of good communication and how to implement them are a requirement to understand why it can save time and effort in the long run.
Related links
https://martinfowler.com/articles/is-quality-worth-cost.html
