Four goals of Agile documentation: Part one

“Working software over comprehensive documentation” is one of the Agile Manifesto’s four value statements. You may well be one of those people who believe that documentation is a waste of effort because it’s outdated as soon as it’s created. You might believe that your code is self-documenting or that UML diagrams belong in the 90s. But it’s a mistake to think there’s no value in documentation.

The manifesto style phrasing of “A over B” has a footnote of course: “While there is value in items on the right, we value the items on the left more.” So while there actually is value in the documentation, we value working software more. And we definitely value working software more than comprehensive documentation.

So what level of documentation is enough? As with so many things in software development: it depends. There’s, unfortunately, no fixed set of rules to apply. But to determine how to do just enough of any activity, focusing on the value that activity creates is a good start. Ask yourself why you should create a piece of documentation, and then balance and prioritize the effort according to its value.

This two-part article will talk about and give examples for four communication benefits documentation can bring in an agile software delivery team. The first two are covered in Part One, the others in the follow-up piece.

Documentation is a vast area. It can be done in lots of different mediums, describing many different aspects of software for various stakeholders. Here, we focus on how developers can use high-level documentation to communicate inside a team, and with direct stakeholders. All of these are things that can complement the documentation already provided by code, scripts, and tests.

1. Create a common understanding

I often catch myself working under the assumption that everybody on the team has the same understanding of what we are doing. “Surely the view of the architecture in my head is clear to everybody?” That would imply we don’t have to write these seemingly obvious things down or have a sketch on the wall. This is a fallacy that, in my experience, especially more tenured developers on the team are prone to.

Architecture show-and-tell

To verify how accurate our assumptions about common understanding really are, you need to get each team member to lay out their understanding. You can do an exercise in your team where you break into groups, have everybody put together their view of the architecture and then present back. This can help surface misunderstandings and complement each other’s knowledge. You also come out of it with an overview picture to evolve and use in future discussions and onboardings.

Figure 1: Creating shared values

The wall of common understanding I always like to reserve some space for a “wall of common understanding” with overview pictures of core concepts. The contents of this wall depend on the software at hand. There’s usually some form of a systems overview with external dependencies, frequently a component and technology stack overview. If the environment setup is elaborate, you might put that up; if it’s really simple, you might decide not to waste space on it.

Figure 2: Example of a wall of common understanding

Regardless of what ends up on this wall, it’s important to set a space constraint. For example, if the team is co-located, this could be a piece of wall space that holds six or eight sheets of paper. Then you fill that space with everything that you believe everybody on the team should know about the state of the system you’re building. The space constraint is useful because we can usually only keep a limited amount of things at the forefront of our minds anyway. The goal here is to identify the essence of what everybody should know so that you can work towards your goals efficiently. Doubling the space just because you’re working on a very large system will dilute that purpose.

Identifying candidates for the wall

• What are you always explaining to new team members within their first week?
• What do you often need to explain to stakeholders to give them a high-level overview of the system?
• What does not change frequently?

2. Surface and understand complexity

As developers, we strive for simplicity in our software, and “self-documenting,” well readable code. In spite of this, we’ll always end up with parts that aren’t trivial, yet critical. Creating documentation for these parts, in particular, is important. That makes it not only easier to explain them, but also helps to evaluate if the implementation makes sense, and to uncover accidental complexity.

Infographics

The format of “infographics” has helped me with this type of documentation. Take an example of a team building an offline-first web application. In this architecture, we had modules for data synchronisation, data model migrations, and conflict, all of which are inherently complex concepts. We built them in the beginning, and then rarely touched them as the development continued. Using infographics to describe these concepts gave us a concise overview without simplifying things too much and hiding the complexity. They’re a mix of graphics and text, with a relatively high level of detail. The reader is supposed to take some time to read and absorb them. This is in contrast to the more high-level overview diagrams mentioned before, where you usually aim for a quick overview.

Figure 3: Example of an infographic

Identifying candidates for infographics

• Complicated things you don’t touch frequently, but every time you do touch them, you have a hard time remembering how it works. The more critical a component like this is to your application, the more important it is to document it.
• You just designed a new part of the system, and you want to check if the design’s simple enough? If you can’t come up with an understandable infographic, that might be a design smell. The thought process of creating the documentation can help make the design even better.

What type of information you put on the wall or turn into infographics can also depend on factors like the seniority of the team, the frequency of change in team composition, the type of application, phase of the project (e.g., how old is the code), or your business domain.
 

Paper widget kits

Another aid I’ve used to facilitate the frequent explanation of a non-trivial part of the architecture is a set of paper widgets. You can use them to build up a picture step by step, as part of a conversation. Our “explain our data model” kit for example contained screen sketches, data entities on index cards, and a set of cards representing our data import jobs. We used it to not only explain the model, but also talk about where the data came from, and what it was used for.


 

Identifying candidates for widget kits

• Parts of the software that has a lot of history, and lots of things “between the lines” that are hard to put in writing.
• Things that I prefer having a conversation about, instead of giving somebody a wiki entry to read.
• Things with a large scope, where a step-by-step explanation helps understanding.

In Part Two of this article, I’ll discuss how to help our future selves make more informed decisions, and how to use documentation to create empathy. I’ll also describe strategies to try and keep documentation up to date.