Agile Values: Working Software Over Comprehensive Documentation

In my last post, I talked about the Agile value of individuals and interactions over process and tools. In this post, I’ll discuss the next Agile value: working software over comprehensive documentation.

Like all the values from the Agile Manifesto, this is not a hard and fast rule. There’s still a time and place for documentation. But the goal is to reduce the overhead of creating a lot of unnecessary documentation that will quickly be out of date and therefore misleading to new team members.

One thing that differentiates Agile from Waterfall is the expectation that there is a universal understanding of both what you’re building and why you’re building it. Ideally, everyone on the team has empathy with the user and understands the value of what you’re delivering.

This should start with a company vision and continue to be refined into a vision for the team. From that vision should come a North Star of what you’re trying to achieve for your user. This goal may shift a bit as you continue to understand your user and the market better, but the general direction will always stay the same.

It’s important that everyone on the team understand this because there are many small architecture decisions that are made every day that will contribute to the continued scalability of the product.

Having a vision and a high level concept of the underlying architecture that support this vision are important and should absolutely be documented. These are important artifacts that the team can refer to when they’re thinking about how to implement the next round of user stories.

However, when it comes to implementing specific user stories, in lieu of spending a lot of time doing upfront technical implementation documentation, create the software and then document what you’ve done. This may be in the form of formal documentation, although I’d encourage you to just keep comments in the code where it’s easily referenceable.

The challenge with spending a lot of time upfront creating heavy technical documentation is that as soon as someone starts coding, all that work will be out of date. Even worse, when a new person joins the team, they’re handed this technical documentation and told, “Read this, it’s about 80% accurate.” They start digging into the code and it doesn’t quite match the technical documentation, but it’s never clear if they don’t understand the documentation or the code is actually different.

The Agile Manifesto says, “Don’t do that!”

Spend the time documenting what matters—vision and high-level architecture guidance for scalability—but don’t bother documenting things that will quickly change. Instead, focus on writing the code and document what you’ve done. You will implement features faster, learn faster, and create more value for your users faster, while spending less time on documentation that will quickly be out of date.