🚀 What’s the Real Deal with Documentation in Agile? 🤔

The approach to documentation that Agile and Extreme Programming take is sometimes misunderstood or misinterpreted. Some think Agile (and XP) means no documentation at all, but that is simply not true! So, let’s discover what actually are the Agile and XP point of views about documentation!

Introduction

Documentation is a frequent source of heated discussion when it comes to Agile practices. Discussions can become rather animated as people from different backgrounds and experiences bring their unique viewpoints to the table. Some people say that Agile and documentation cannot coexist because they are incompatible, comparing them to oil and water. On the other hand, other people believe that documentation is an essential and crucial component of the Agile process.

Maybe you are one of the believers that Agile says to avoid documentation completely. We’re here to debunk this myth.

The approach to documentation that Agile and Extreme Programming take is sometimes misunderstood or misinterpreted. So, in this post, we’ll go into the essence of XP and expose the true nature of Agile documentation as it relates to this powerful and dynamic methodology.🚀📝

The Truth About Documentation in Agile

Let’s start by stating the truth very clearly: in no way does Agile Manifesto, XP, or any other Agile-related methodology suggest avoiding documentation completely.

I mean, that wouldn’t make any sense, right? Some documentation is just needed, sometimes. Think about audits, support, onboarding, tracking decisions, brainstorming — there simply are good reasons to document stuff, sometimes.

The only real take about documentation is:

We are uncovering better ways of developing software by doing it and helping others do it. Through this work we have come to value:

[…]
Working software over comprehensive documentation
[…]

That is, while there is value in the items on the right, we value the items on the left more.

The Agile Manifesto states very clearly that “there is value” in documentation, but working software is considered more important — and hopefully, this is something we all agree on.

The problem is that, over time, some people misunderstood this sentence and spread the idea that all documentation should be avoided. This is simply not true and is one of the things that contributed to making people skeptical about Agile.

Still, most people underestimate that statement — and I think that to clarify it we need to bring eXtreme Programming’s take on documentation when describing the principle of “mutual benefit”:

Extensive internal documentation of software is an example of a practice that violates mutual benefit: I am supposed to slow down my development considerably so some unknown person in the potential future will have an easier time maintaining this code.

This is the big problem with extensive documentation in most organizations, IMHO: while some consider the cost of documentation, almost no one considers the ROI of that cost — that most of the time is very low.

Writing technical documentation has a lot of issues:

• writing good technical documentation is hard, for multiple reasons:
• even writing well in general is hard
• writing good technical documentation is a different job than writing code
• async written communication is generally less efficient than sync conversations (and the fact that writing well is hard doesn’t help)
• it is completely detached from the codebase, so you need to invest effort to be sure either you don’t have duplicate info between code and doc or to keep that duplicated info in sync

I’m sure most of you feel related to those problems, but you probably think that documentation is still important and we just have to do it.

I agree, we need certain types of documentation, but not all.

The heuristics we should care about

From all the ways to think about software documentation, I like the approach of splitting it into two main categories:

• Product documentation → here we have all the documentation we write for users (both internal and external), but also all the documentation related to the system — for example, API public documentation and Architecture documentation fall into this category
• Process documentation → here we have all the documentation we produce during the process of development = for example, user stories and meeting notes fall into this category

We can safely say, IMHO, that Product documentation is the most important one to invest in — because it will last over time; Process documentation instead, is only useful in the process, then it becomes mostly useless.

This is one of the keys to approaching documentation in an Agile (and smart) way: consider trade-offs like we always do in code (or should do!). If the Product doc is more important, we want to invest more time in it compared to the Process doc.

Talking about the mutual benefit example we discussed earlier, the solution is not to don’t write documentation at all — XP simply suggests a different approach:

• Invest time in writing automated tests instead of documenting the code what it should do and how to use it — this way not only benefit will be mutual (for both the current dev and the future one) but in general the code will be easier to read and maintain
• Invest time in refactoring instead of documenting the code to explain what it should do in detail — this way, we can remove accidental complexity and improve readability, giving the current dev more satisfaction and fewer defects, and also an easier-to-understand code for the future dev
• Invest time in names to make them explicit and coherent, so that the current dev works faster and future dev will easily read it

The point is not to avoid documentation, but to handle it in a professional and smart way — not writing any doc or writing too much doc without thinking are just 2 faces of the same, problematic coin.

Basically, we should handle the documentation the same way we treat code and tests: the less it is, the better; the more automated it is, the better; the less duplication there is, the better; and so on.

Here are the principles and heuristics that we can follow to face documentation in an effective and sustainable way:

• Code should be self-documenting → the right place to read what the code does is the code itself: instead of writing documentation to describe it, refactor it to make it readable
• Tests are living documentation → tests are still code, and they basically are examples of usages of the code under tests: make tests readable so that they can actually be useful as documentation
• Automate all the documentation possible → writing documentation is painful, and keeping it updated with changes is even more painful — be sure to always ask yourself if a piece of documentation can be automated, and pick your tools to enable the automation chances; documentation is costly, we need to reduce that cost
• Keep documentation close to what it describes → instead of having a single place for documentation, make sure you document something very close to where you use it — a centralized wiki makes a lot of sense for company-wide and product documentation, but, for example, document your codebase in the repository itself
• Write just enough documentation → “just enough” means be sure you write all that truly matters, in a clear way, but no more; it also means be sure to cover all that matters
• Write documentation “just in time” → before documenting, wait. Produce documentation when it’s needed, not before — a similar approach to creating an abstraction: do not do it immediately, wait until the last responsible moment when you are sure you need it and most information is now steady and not changing continuously.

Just as clean code and solid architecture contribute to a healthy project, so does comprehensive and well-maintained documentation — and missing/wrong/bad documentation also contributes to technical debt, so again, “just enough”: write all that’s important, but no more.

This synergy can help us steer clear of the ever-dreaded tech debt, maintaining a system that’s truly agile, adaptable, and ready for the future.

Until next time, happy coding! 🤓👩‍💻👨‍💻

🙏 Thank you for reading this shortened version of the article. If you like it and want to read the full version, you can find it on my blog here.