loading...
Cover image for Does remote work make software and teamwork better?

Does remote work make software and teamwork better?

david_whitney profile image David Whitney Originally published at davidwhitney.co.uk ・6 min read

I woke today with an interesting question in my inbox, about the effectiveness of remote work and communication, especially during the global pandemic:

Diego Alto: Here's the statement

"Working remotely has an added benefit (not limited to software) of forcinwg documentation (not only software!) which helps transfer of knowledge within organizations. (I am not just talking about software).

Example: a decision made over a chat in the kitchen making coffee is inaccessible to everyone else who wasn't in that chat. But a short message in slack, literally a thumbs up in a channel everyone sees, makes it so.

Discuss"

Let's think about what communication really means in the context of remote work, especially while we're all forced to live through this as our day-to-day reality.

Tools are not discipline

High quality remote work requires clear, concise, and timely communication, but I'm not sure that it causes or facilitates it.

I think there's a problem here that comes from people learning to use tools rather than the disciplines involved in effective communication - which was entirely what the original agile movement was about.

DHH talks about this a lot - about how they hire writers at Basecamp, their distributed model works for them because they have a slant towards hiring people that use written communication well.

I find this fascinating, but I also have a slightly sad realisation that people are unbelievably bad at written communication, and time is rarely invested in making them better at it.

This means that most written communication in businesses is waste and ineffective and may as well not have happened. Most of the audit trails it creates either get lost or are weaponised - so it becomes a case of "your mileage may vary".

Distinct types of written communication are differently effective though, and this is something we should consider.

Different forms of communication for different things

Slack is an "ok form of communication" but it's harmed by being temporal - information drifts over time or is repeated.

But it's better than email! I hear you cry.

Absolutely, but it's better because it's open and searchable. Email is temporal AND closed. Slack is an improvement because it's searchable (to a point) and most importantly a broadcast medium of communication.

It's no surprise that slack and live chat has seen such a rise in popularity - it's just the 2010's version of the reply-all email that drove all of business through the late 90s and early 2000s.

Slack is basically just the millennial version of reply-all email chains.

Both forms of communication are worse than structured and minimal documentation in a known location though.

"Just enough" documentation - a record of decisions, impacts, and the why, is far more effective that sifting through any long-form communication to extract details you might just miss.

Co-location of information

I'm seeing a rise in Architecture Decision Records (ADRs) and tooling inside code repositories to support and maintain them for keeping track of decisions.

An architectural decision record (ADR) is a document that captures an important architectural decision made along with its context and consequences.

There's a tension between the corporate wiki, which is just rotten and useless, and "just read the code bro".

"Just read the code" is interesting, as it's a myth I've perpetuated in the past. It's an absolute fact that the code is the only true and honest source of understanding code, but that doesn't mean "don't give me a little bit of narrative here to help me".

Just enough

I don't want you to comment the code, I want you to tell me its story. I want you to tell me just enough.

I've done a bunch of stuff with clients about what "just enough" documentation looks like, and almost every time, "just enough" is always "co-located with the thing that it describes".

Just enough means, please tell me -

  • What this thing is
  • Why it exists
  • What it does
  • How to build this thing
  • How to run this thing
  • Exactly the thing I'll get wrong when I first try and use it

Any software or libraries that don't ship with this information, rot away, don't get adopted, and don't get used.

I'm glad the trend has taken hold. ADRs really fit into this "just enough" minimal pattern, with the added benefit of growing with the software.

The nice thing about ADRs, is they are more of a running log than a spec - specs change, they're wrong, they get adapted during work. ADRs are meant to be the answer to "why is this thing the way it is".

Think of them as the natural successor to the narrative code comment. The spiritual sequel to the "gods, you gotta know about this" comment.

Nothing beats a well-formed readme, with its intent, and a log of key decisions, and we know what good looks like.

Has remote work, and a global pandemic, helped this at all?

On reflection, I'm not sure "better communication" is a distributed work benefit - but it's certainly a distributed work requirement.

I have a sneaking suspicion that all the global pandemic really proved was that "authoritarian companies that didn't support home work was nothing more than control freakery by middle management".

There's nothing in the very bizarre place the world finds itself that implicitly will improve communication, but we're now forced into a situation where everyone needs the quality levels of communication that was previously only required by remote workers.

Who needs to know how things work anyway?

People that can't read code have no concern knowing how it works, but every concern in understanding why it works and what it does.

Why.
What.
Not how.

Understanding the how takes a lot of context.

There's a suitable abstraction of information that must be present when explaining how software works and it's the job of the development teams to make this clear.

We have to be very aware of the "just enough information to be harmful" problem - and the reason ADRs work well, in my opinion, is they live in the repository, with the code, side by side with the commits.

This provides a minimum bar to entry to read and interpret them -and it sets the context for the reader that understanding the what is a technical act.

This subtly barrier to entry is a kind of abstraction, and hopefully one that prevents misinterpretation of the information.

Most communication is time-sensitive

There's a truth here, and a reason - the reason slack and conversations are so successful at transmitting information; Most information is temporal in nature.

Often only the effects communication needs to last, and at that point, real-time-chat being limited by time isn't a huge problem.

In fact, over communication presents a navigation and a maintenance burden - with readers often left wondering what the most-correct version of information is, or where the most current information resides, while multiple-copies of it naturally atrophies over time.

We've all seen that rancid useless corporate wiki, but remember it was born from good intentions of communication before it fell into disrepair.

All code is writing

So, remember that all code is writing.

It's closer to literature than anything.
And we don't work on writing enough.

Writing, in various styles, with abstractions that should provide a benefit.

And that extends to the narrative, where it lives, and how it's updated.

But I believe it's always been this way, and "remote/remote first" rather than improving this process (though it can be a catalyst to do so), pries open the cracks when it's sub-par.

This is the difficulty of remote.
Of distributed team management.

It's ironically, what the agile manifestos focus on co-location was designed to resolve.

Conflict is easier to manage in person than in writing.

You're cutting out entire portions of human interaction around body language, quickly addressing nuance or disagreement, by focusing on purely written communication. It's easier to diffuse and subtly negotiate in person.

The inverse is also true, thoughts are often more fully formed in prose. This can be both for better or worse, with people often more reticent to change course once they perceive they have put significant effort into writing a thing down.

There is no one way

Everything in context, there is no one way.

The biggest challenge in software, or teamwork in general, is replacing your mental model with the coherent working pattern of a team.

It's about realising it's not about you.

It's easy in our current remote-existence to think that "more communication" is the better default, and while that might be the correct place to start, it's important that the quality of the communication is the thing you focus on improving in your organisations.

Make sure your communication is more timely, more contextual, more succinct, and closer in proximity to the things it describes.

Posted on by:

david_whitney profile

David Whitney

@david_whitney

Software consultant. Bestselling Author. Loves rum, alt culture, games & metal. Formerly Head of engineering, chief technical architect, head principal engineer, lead dev, etc.

Discussion

markdown guide
 

I don't use the πŸ¦„ button often, but here you go. This piece deserves the extra attentionβ€”not that I'm some guru on good content, but I really loved how you covered this broad topic and I definitely think it needs more attention in general.

 
 

"Tools are not discipline" - true but using better communication / process tools does help with discipline. Think of it this way - if you are in charge of tightening screws and you only have a hammer, well the result will not be disciplined for sure.

 

I've always favoured what I call "rituals" things people do instinctively because they work for them. Tools can help correctionally, but unless people understand why they're doing the things, they'll never engage with them meaningfully.

You can see this every time someone writes a As a / I can / So that styled user story, and is then unwilling to change it because they don't realise it was meant to be a prompt for a discussion, or every time someone does a stand up and rambles about implementation detail.

Tooling often promotes the artifact, over the process and communication style that is meant to produce it.

 

I agree with you except for the implication that we can somehow remove all tools. Email, chat, group chat, and bug trackers are all tools. Even if we exactly
"The most efficient and effective method of
conveying information to and within a development
team is face-to-face conversation."
then that's a meeting and a meeting is a tool. Its not a question of tools versus no tools but of effective tools versus less effective tools. Not understanding the tool set being used comes from not viewing them as tools at all but as some sort of gospel to be followed. If developers correctly understood their communication / process tools then they would question them like they do their IDEA or choice of Javascript framework.

You can totally remove all tools, but I'd not suggest that :)
Tools are meant to make your working processes easier, but if you don't understand that process regardless of the tools, it's a folly.

 

Thanks, great read! I definitely agree that communication is often a weak spot among developers, especially written forms of communication, and remote work just made it painfully obvious. I believe standardization or adoption of some common ground principles could help resolve this situation to a certain degree. Like, understanding that we work in teams and should work out common code patterns and styles and stick to it. I've had issues with this in the past in several companies. It is great to work alone in this regard, but having a few more heads to think about a problem certainly helps in more ways than one. It also creates issues like the one we're talking about - effective (sometimes written) communication.

Thanks. Your article gave me a few things to chew on in free time!

 

[EDIT: IDIOMS not idiots ;) ]

I feel like some of the idioms from successful open source projects can be taken through into a template of communication. Though heaven forbid not the entitlement ;)

Strong conventions over readmes, discoverability of ADRs and diagrams, and actually a lot of the "communication about code" works well. The more meta project / program management stuff I feel is the realm of product management - so should be captured in things like living product canvases.

Certainly my personal take :)

 

The phrase "why is this thing why it is" doesn't make sense to me. Did you mean "why this thing is what it is"? Or did you mean something else?

 

Great catch - "the way it is" :)