This article is part of a series on remote working.

OK, a quick recap…

In the last article we looked at the spectrum of synchronousness, which showed how there exists:

• A continuum between synchronous and asynchronous communication.
• Implicit expectations with that communication depending on the medium and format you choose to communicate with.
• A need to shift right along this spectrum in order to better support remote and distributed working.

In this article we’re going to look at permanence.

Permanence

Whenever you communicate, you create artifacts. These can range from a memory of a conversation in a colleague’s brain through to a detailed written proposal. Similar to the continuum between synchronous and asynchronous, there is also a correlating continuum between permanence and impermanence. 

But what do we mean by that?

#define

• A permanent artifact is one that has a quality of lasting or remaining unchanged indefinitely.
• An impermanent artifact only lasts for a limited period of time.

There are several dimensions on which to determine the permanence of an artifact, both now and in the future:

• How relevant is it? Does it accurately represent a decision, system or process if somebody was to find it?
• How accurate is it? Does it fully document its subject matter, or does it require additional information from elsewhere in order to fully describe it? Could it even be out of date?
• How useful is it? If somebody was to search for and find this information, is it a good use of their time to read it?

We’ve all experienced permanent documentation that has been misleading. This is because as humans we are excellent at creating artifacts to address our current needs, but we don’t always bring our attention fully to what will happen to those artifacts in the future. We need to be mindful of this fact. Are we making the future better? Or are we setting a trap?

Look at the correlation between permanence and synchronousness in the diagram below.

As you can see, synchronous communication generates very few artifacts for the future. Asynchronous communication, on the other hand, does not work without these artifacts being created. 

In a workplace that is centered around physically colocated offices, our bias towards synchronous communication leaves no audit trail, which is why remote workers often find it difficult to feel integrated if they are not party to synchronous, in-person communication. Did it even happen?

There are some key principles to follow in order to make sure that you create good quality artifacts that last into the future and enable distributed and remote working. These principles can be applied at the individual, team, department or company level.

These are:

• Leave an audit trail
• Maintain an index, and
• Mark, file, tidy and delete.

We’ll look at these in turn.

Leave an audit trail

Some of the tools that we use to develop software have evolved to create audit trails as a feature. For example, take version control systems like git that allow us to inspect – and even replay and change – the history of commits in a software project. We can often go back in time and understand what happened and why. 

This is great.

However, we should be thinking of applying the same principles of leaving an audit trail from our communication and decision making. We should pay attention to showing our working by applying the shift right on the spectrum to whatever we are doing. For example:

• As we go about our day, we should keep our team informed about what we’re working on by writing updates in a team chat channel.
• When we have an informal chat and make a decision about something, we should broadcast that decision via a written form, such as in our team chat or via email.
• At the end of a week, we could write a brief update to each other about what we’ve been working on and why, and what we’re focussing on next week.
• When having meetings, we should maintain an agenda with notes that contains the history. Additionally, we should record each meeting in that series and store it in a shared file system.
• When starting new projects, we should work on our ideas in design documents that anyone can view, ideally storing all design documents in a central place so that anyone can discover them later.
• When we make a major architectural decision in a codebase, we should document exactly why we made that decision and how it affects the structure of the code going forward.

Leaving an audit trail can seem like hard work if you’ve not been used to doing so. However, once you start, you’ll notice that it has numerous advantageous effects on the way that you do your work. 

Even if you’re working alone, you gain more opportunities for interaction with others through your audit trail, which is especially important with remote working, and writing while you think helps develop your critical thinking skills.

Maintain an index

Regardless of whether you are an individual contributor, manager of one team, or of a whole department, creating indexes of information is essential for keeping your house in order, increasing the discoverability of artifacts, and also encouraging others to work in this way.

Search engines for our documents at work are not in any way as good as the ones we use to search the internet. You can just never find that document that you were after. What was it called again? Was it “2021 projects” or “team allocations”? Did it have a typo in the title? Was it even stored here?

Maintaining indexes can be a great way of making the important items discoverable for everyone. It could be as simple as a shared document with hyperlinks in it that anyone can edit. 

For example, for a team, the index could contain:

• A quick overview of what the team is called and what they are working on.
• The members of the team and how to contact them individually.
• Links to their team chat channels and email groups.
• Links to the code repositories that they own and are working on.
• Links to shared folders with design documents and architectural diagrams for current and past projects.
• Rolling meeting agendas and recordings.

This index could be linked to in the staff directory, their chat channel, and in the codebase documentation. It doesn’t take long to create, but it can be the beginning of numerous shift right habits that begin to contribute to making the index and the linked documentation increasingly better. 

Humans have a habit of mirroring other behaviors that they like, so it won’t be long before other individuals and teams start their own indexes as well.

Mark, file, tidy and delete

It’s all well and good continually shifting right along the spectrum and creating all of these new artifacts in order to better support remote and distributed working. However, artifacts often have a shelf life. 

A design document that assists a productive discussion and decision today may just waste an hour of someone’s time in a year when they don’t realize that it is no longer relevant. It is your duty to ensure that you are keeping your proverbial closets tidy with good habits.

Thinking back to our spectrum of synchronousness and permanence diagram, there is a general observation that we could make:

• Artifacts that are produced from communication closer to the left-hand side of the spectrum will typically have a short shelf-life.
• Artifacts that are produced from the right-hand side of the diagram will typically have a long shelf-life.

The video recording of a meeting probably isn’t going to be an artifact that you’ll want to come back to in several years, but it may be useful for people to catch up on the content in the weeks following it. However, the README file for a software project should probably be evergreen: that is that it’s as relevant today as it will be in the future.

So, what this means is that:

• Short-lived artifacts should be labelled as such. This can happen implicitly (e.g. an old code commit is implicitly short-lived, since there are commits after it in the same file) or explicitly (e.g. a written summary that is no longer useful is marked as “old”, or is archived away, or even deleted).
• Long-lived artifacts should be kept up to date. Any unmarked written document or wiki page should be occasionally revisited and updated to ensure that it is still relevant and useful.

Conflict usually occurs when there is a violation of these principles, which often happens towards the right-hand side of the spectrum of synchronousness. Wikis or READMEs stagnate, but it is often not clear that they have, and then they waste somebody’s time. Written documents can become irrelevant, but they are not marked as such.

Always make it clear when you are creating a short-lived or long-lived artifact. Appropriately labelled short-lived artifacts can be forgotten about, as future readers will understand that it is likely no longer relevant if they stumble upon it. Long-lived documents need tending to with time to remain evergreen.

Continually review, mark, file, tidy and delete your artifacts. Your future self and colleagues will thank you for it.

Takeaways

Here’s the homework for this week.

• Begin increasing your audit trail. Blog updates on what you’re working on in your team channel with links to pull requests, tickets and comments. 
• Write a daily or weekly update to your team about what you worked on, what went well, what didn’t, and what you’re focussing on in the next time period.
• Discuss the idea of creating an index with your team. What should be in there? Then create it!
• Search through your shared filesystem to find the oldest and most irrelevant document. Share it around if it’s humorous. How did it end up like this? What strategy would have prevented it getting into this state?

Next time we’ll look at the correlation between becoming more asynchronous and the effect it has on feeling connected to others.