It depends, and thoughts on good/bad collaboration

Hello everyone!

Welcome to the 28th edition of this newsletter. As a fitness enthusiast software engineer working for a fitness company, I am focussed on software engineering and fitness pretty much all the time. In both these areas, there are very few definitive answers - context is king. “It depends” has pretty much become my mantra over the last few months. Ergo, I have decided to rename this formerly eponymous newsletter “It Depends” starting this week. Same awesome content under a more fun name.

Let’s get on with it.

The value of collaboration, talking to your team and your customers is in the brainstorming stage or in the learning phase. This is where we should put together our collective minds, bounce ideas, and figure out the next steps. Once this stage is crossed and we enter the execution phase, collaboration becomes a dangerous overhead.

If multiple teams and people must build something new together, synchronization is inevitable to some extent. However, there is a specific type of low-impact collaboration where people talk to each other to find out what capabilities exist and how to use them. This is seen when a product team tries to onboard to a platform by first setting up a meeting on how to use it. This is seen in “integration war-rooms” where two teams try to set their systems up correctly to talk to each other. This is seen when our teammates ping us about the right way to use that API we wrote the other day. This conversation is not about building new stuff, it is about figuring out how to use what exists. In my opinion, this is utterly wasteful.

Developers obsess about making all business interactions self serve. In operations heavy organizations, teams spend a significant amount of bandwidth building tools for “enabling” operations teams. The same engineers, however, are perfectly okay sitting with team after team in meetings to explain to them how to use their software. Working with non-engineering teams is considered overhead, working with other engineering teams is collaboration.

The deeper a team’s systems are in the architecture stack, the more they are likely to be reused. The more people want to use them, the more this team needs to answer questions around what and how. The more time they spend answering these operational questions, the lesser time they are actually building cool new stuff. A perfect vicious cycle. Teams and individuals spend an immense amount of time simply explaining how things work to others.

This situation is clearly less than optimal, so how can we do better?

This is not so much a problem as a shift in perspective. As engineers, we often consider all engineering as internal, and capable of being able to navigate convoluted technical processes. The thing to keep in mind is that they shouldn’t have to. Just like operations and other “business” teams, if other teams and developers have well-defined SOPs for using your code, we will have gone a long way towards removing unnecessary human collaboration.

In this world of operational excellence, there are two tools that stand heads and shoulders above all other techniques – documentation and design. What if we think of all software work as building a product? My customers, who happen to be other engineers in this context, should be able to explore and understand my product, play around with it, and then finally sign up for it with minimum human intervention.

For them to be able to do this, documentation is a powerful tool. Imagine if your system’s documentation was up to date, had clear guidelines on how to do what, and explained the different scenarios. Wouldn’t that be great? The world of operations practically runs on this type of documentation – detailed, precise, and explicit. The problem is that this type of documentation is hard to maintain, especially in the world of agile software. Also, no one read docs. People are far more likely to ping the author of the document for a meeting rather than go through something very detailed. This is why I consider documentation a supporting actor in this play.

The single most important tool that we can bring to bear on this problem, in my opinion, is good design. When the system is exposed in such a way that the user cannot make a mistake in using it, then the very core of the problem goes away. Documentation can further bolster this good design by herding stragglers to the right place, but the entire experience of using a system or tool or API should be explicitly designed to make the user do the right thing unambiguously.

This is not an outlandish idea. This is what product thinking, as applied to most customer products, is. It’s just that engineers mostly don’t apply the same thinking to developer tools. Pretty much always, customer experience > internal tools experience > developer experience. This is kind of sad because developer experience is where the entire engineering organization spends its time. Imagine what your team could achieve if every experience of using a new software thing was as smooth as your company’s customer experience.

“How should I use it” indicates a failure of design and requires focussed product thinking to fix it. It is worth the effort because answering this question is the lowest form of collaborative value-addition. I hear a lot of developer feedback on the lines of “X is a great dev because he really spent a lot of time helping me use her system”. While I do not disagree with the sentiment, X and X’s team have also failed in prioritizing their time. They could have been discussing and building the next set of things. Instead, they ended up doing some grunt work that could very likely have been automated.

While writing a new class or a new method, ask yourself if your teammates are going to have to ask you how to use it? If your system is to be used by other teams, will they have to ask you how to get started? Will you have to make some manual DB entries or change some configurations? Is there any step where you must “talk” to them to explain things? If so, then regardless of how useful the thing you just built, you have increased the communication overhead in your organization which you will be paying, personally, many times over the next few weeks or months or worse.

I’d love to hear more from you about how much of your time goes into what kind of collaboration, and what value do you think it brings to the table. This article only expresses my narrow experience, and it would be instructive for me to learn from others who have different kinds of organizations than mine. Are there other tools/processes that can make a team more effective? Drop an email with your ideas.

From the great interweb

  1. Dan North argues that SOLID is outdated and suggests CUPID instead. What do you think?
  2. Nick Tune has written about how misaligned incentives fuel organizational dysfunction. Not exactly a hot take, but a well-written article nonetheless.
  3. I hate rewrites, but sometimes they are needed. It depends :). Ian Small explains how Evernote went about doing a complete rewrite of their app.
  4. This Twitter thread questions the efficacy of pull requests as a mechanism for building shared knowledge in a team. I personally think pull requests and code review are a great mentoring mechanism, but the thread makes some interesting points.

That's it for this week folks. Have a great weekend!


Modify your subscription    |    View online