The Spectrum of Permanence

Create Useful, Tidy Artifacts for Your Colleagues and Future Self

📚 Connect with us. Want to hear what’s new at The Pragmatic Bookshelf? Sign up for our newsletter. You’ll be the first to know about author speaking engagements, books in beta, new books in print, and promo codes that give you discounts of up to 40 percent.

Synchronous Recap

This article is one in a series, so let’s start with a 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.

Whenever you communicate, you create artifacts — a record of what took place. These artifacts range from a remembered conversation with a colleague to a detailed written proposal. Just as there is a continuum between synchronous and asynchronous, there is a continuum between permanence and impermanence.

But what do we mean by those terms?

#define

• A permanent artifact is one that lasts or remains unchanged indefinitely.
• An impermanent artifact lasts for only a limited time.

To determine the permanence of an artifact, both now and in the future ask:

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

We’ve all experienced misleading permanent documentation. As humans, we are excellent at creating artifacts to address 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 artifact longevity. Are we making the future better? Or are we setting a trap?

Reflect on the correlation between permanence and synchronousness shown in the following diagram:

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

Creating Quality Permanent Artifacts

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 the synchronous, in-person communication — did it even happen?

Following some key principles helps ensure that you create good quality artifacts that last into the future and enable distributed and remote working. You can apply these principles at the individual, team, department, or company level.

The principles for creating quality permanent artifacts are:

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

We’ll look at each of these principles in turn.

Leave an Audit Trail

Some software development tools have evolved to create audit trails as a feature. For example, consider version control systems like Git. These systems allow us to inspect (and even replay and change) the history of commits in a software project. We can look back in time and understand what happened and why — which is great.

However, we also need to leave an audit trail for communication and decision making. To create this trail, shift right on the spectrum for all communications. For example:

• Team updates. Keep your team informed about what we’re working on by writing updates in a team chat channel.
• Weekly individual updates. Everyone should write a brief update at the end of each week and share it with the team. Updates should include what the person worked on this week (and why) and their focus for the upcoming week.
• Meetings. Maintain an agenda with notes that contain meeting history. Additionally, record each meeting in that series and store recordings in a shared file system.
• Design documents. When starting new projects, record ideas in design documents that anyone can view. Store design documents in a central place so that anyone can discover them later.
• Decisions. When you make a decision based on an informal chat, broadcast that decision via a written form like team chat or email.
• Architectural decisions. When making a major architectural decision in a codebase, document precise reasons for that decision and how it affects the structure of the code going forward.

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

Even if you’re working alone, you’ll gain more opportunities for interaction with others through your audit trail. This connection 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 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 important items discoverable for everyone. Your index could be as simple as a shared document with hyperlinks that anyone can edit.

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

• Overview. A quick overview of what the team is called and what they are working on.
• Members. Members of the team and how to contact them individually.
• Communication channels. Links to team chat channels and email groups.
• Code repositories. Links to the team’s current code repositories.
• Design documents. Links to shared folders with design documents and architectural diagrams for current and past projects.
• Meetings. Rolling meeting agendas and recordings.

Link to the index in the staff directory, the team’s chat channel, and in the codebase documentation. Such links don’t take long to create but can launch numerous shift-right habits that contribute to making the index and the linked documentation increasingly better.

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

Mark, File, Tidy, and Delete

It’s all well and good to continually shift right along the spectrum, creating new artifacts to better support remote and distributed working. However, most artifacts have a shelf life.

A design document that enables a productive discussion and decision today may just waste an hour of someone’s time in a year. When they access the document, they won’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, here is a general observation:

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

The video recording of a meeting probably won’t be an artifact you’ll revisit in several years, but it may be useful for people to catch up in the weeks immediately following the meeting. In contrast, 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 spectrum of usefulness means is that you must:

• Label short-lived artifacts. Labeling can happen implicitly. For example, an old code commit is implicitly short-lived since there are commits after it in the same file. Or you can explicitly label an artifact. For example, mark a written summary that is no longer useful “old,” archive it, or even delete it.
• Keep long-lived artifacts up to date. You will need to periodically revisit any unmarked written document or wiki page and update it to ensure that it is still relevant and useful.

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

Always make it clear when you are creating a short-lived or long-lived artifact. You can forget about an appropriately labeled short-lived artifact, as future readers will see it is no longer relevant if they stumble upon it. Long-lived documents you must tend to so that they remain evergreen.

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

Takeaways

Creating quality permanent artifacts helps remote workers feel integrated. To ensure artifacts last into the future and contribute to effective distributed and remote working you’ll need an audit trail; an index; and the discipline to continually mark, file, tidy, and delete.

Here’s the homework for this week.

• Begin increasing your audit trail. Write blog updates about 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. Tell them 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. Find the oldest and most irrelevant document. Share it around if it’s humorous. How did the document end up like this? What strategy would have prevented it from becoming hilariously irrelevant?

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

If you enjoyed this article, be sure to pick up James Stanier’s books from The Pragmatic Bookshelf:

Further Reading

Also by James Stanier:

Become An Effective Software Engineering Manager on Medium:

Originally published at https://www.theengineeringmanager.com on February 18, 2021.