How meetings destroy software quality

July 21, 2022 7-minute read

software • lead

1. Abstract

I was debugging a microservice. It was my first time with this code. I realized that everything works till Redis, which is probably not updated. That’s why end users don’t see what they should. The hypothesis was sound and worth testing, but how to do it?

How to debug Redis within this codebase, in this setup, and in this environment? It was not my team’s microservice, so the fastest way would be to ask the other team who owns it. That is silly if I have to talk to the authors each time I want to do something that is a code smell. It probably says something about the missing documentation or about the quality of the software. Why quality? Writing high-quality code is writing readable and easy-to-change code.

Before I went to DuckDuckGo and StackOverflow, I opened README.md, and immediately I realized there was an even bigger problem than simply why the cache hadn’t been updated.

2. Meetings

Usually, we hate them, especially those where 100+ people dial in and pretend to be present. Additionally, we may have ad-hoc meetings where some people ask us to help. Those are much more valuable meetings, but think about common themes and add other channels like slack private messages - what is a repeatable theme people always ask you? If we meet and keep answering on those ad-hoc questions, it will weaken our sense of creating easy-to-use software, as we would know that in case something is unclear, someone will meet and discuss how this works.

Do this simple trick: each time you realize someone asks you about something which may come back later, answer this in README.md and send README to this person, that is a real fix for the problem as you have now guaranteed the next person won’t bother you again about this topic, and if they do, you’ll send them the README in few seconds.

3. There is a way to improve

3.1 README.md

In the ideal world, I should be able to look for Redis in README and quickly copy some commands on how to debug, and the job done in 5 minutes. Moreover, I expected there should be a diagram of how it works within the service. There was nothing, not even a line on how to start Redis on local, not to mention how a developer should troubleshoot it in each environment.

How are new joiners and random people from other teams supposed to onboard and debug this microservice?

Firstly, there is a false conviction that documentation is unnecessary when the team is mature. That is a lie, and it causes slowness as very often, we forget how to do simple things, and we have to look for answers. Instead, if there were already researched and prepared on how to do something, it would save the team countless hours.

Secondly, READMe.md is an excellent place for our instructions on how to start and troubleshoot the service. New joiners will probably begin from this file to understand the service. And that is our test. When the person cannot figure out how to troubleshoot our service by only looking into README.md, we should fix it. It will benefit everybody.

Putting a small note on how to do stuff and document our hacks and illogical business decisions dramatically benefits the whole organization. The sole fact that we need to justify our hacks may even stop doing them. If each employee does it, inevitable, all teams will reduce the time to market, the troubleshooting will be less painful, and the number of tickets will decrease as everybody can understand the service and therefore change it and raise Merge Requests.

Thirdly, good README will make new joiners happy, as they can start the service on day one without anybody’s help.

Lastly, our systems become more complex over time, and nothing let us realize it than extensive up-to-date README. Is it time to simplify the system?

I’ve noticed that some people keep local helper scripts out of the repo. It’s good to use scripts, but such a trend does not scale, as every individual needs to spend time and write them. Everyone is doing the same job, classic reinventing the wheel. Instead, the team should develop one version of the script, one standard migration DB script etc. They could be parametrized to support various requirements and operating systems. When we go out from our local disks to version control, we may notice that our way was suboptimal, and someone else had a much better approach. Merge your team’s scripts for great good!

I remember in one of my projects one developer kept spark SQL scripts on his local machine. I asked him if he could share them. These scripts helped me debug and calculate different things needed for analysis. Why was it not committed somewhere to the project? This job security pattern keeps people within the project, as they have the secret knowledge which nobody had, and they can shine in front of inexperienced Leads. However, they are slowing everything down.

3.3 onboard.sh

Nowadays, we like to have infrastructure as a code. We want to have code which sets up the company infrastructure. Whenever I joined a project, I had a not-up-to-date document to follow to prepare my machine. Why not invest the time once and prepare a script which sets up everything? In software, the employee rotation is high, which would certainly reduce our time wasted on unclear instruction. And yes, I know it will be painful to do it for all the systems, but the same is true with written instructions. If something is not coded, it means it is not well understood.

4. Can we remove/reduce number of meetings?

The meetings are spoiling people. They are like comments in code. The ability to call any person at any time seems a good thing, but it removes discipline from us to think about other people will read documentation or access our code. Meetings should be spent on the important stuff, not asking basic questions.

Yes, I’m aware we cannot remove meetings from organizations, not yet. But we can make them more interesting by removing those which are not needed and are boring. Let’s meet only when we need to, brainstorm, exchange ideas, have fun, and leave everything else to be asynchronous communication.

Meeting organizers often forget that:

context switching destroys productivity.
two meetings with one hour gap steal this hour. People won’t be able to switch back to focus on work and then break and go to the next one.
People interact with each other even without official meetings. Give people time to focus on work, trust that they will be proactive and find the best channel to ask for help.
Usually, the first part of the day is the most productive, don’t fill this with silly meetings.
Most of the meetings should be optional.
People should decline all meetings without agenda.
We can record meetings and share them digitally, so we don’t need to attend every single one. It is not school!

5. Summary

High-quality software makes users happy: it does what it should, is easy to change, and has no critical bugs. It is not only about end users but also about employees who build the product. We completely forgot about testing our internal functions.

How fast it is to onboard a new developer,
How easy it is for a random developer from our organization to be able to troubleshoot problems?
Can the UI team integrate with our new API without talking to us?

If we stop treating meeting as a cure for all our gaps and cut corners, maybe someday I will use instructions from a README.md to discover why my request did not update this damn cache on the Test Environment.