Myths of agile: “there’s no documentation in Agile”
Just 200 more pages before I finish this first spec!
Another myth around Agile is that there is no documentation in agile. Once the project is done, the team disappears in a whirlwind of dust, leaving only a handful of hastily scrawled post-it notes behind them. This is actually a hard problem and there is sometimes some truth to this. But we need to think about this carefully and understand:
- what sort of documentation we really need to produce and what we don’t
- for what purpose and what audience the documentation is really for
- when and how people produce the documentation.
I think a lot of Waterfall projects produce too much documentation. A well-run Agile project can produce the right amount of documentation, for the right audience, in the right time and place. This article will dispel the myth that there is no documentation in agile software development.
Types of documentation (for Waterfall and Agile)
First, we need to distinguish between two types: user documentation and internal documentation. User documentation is produced as part of building software and is shipped or made available in some ways to customers. It tells people how to use the product. This might be in the form of user manuals, online help, and so on.
Developer documentation is not part of the product and is not made available to customers. It is materials that describe how or why the product was built in the way it was.
High-Level Solution Designs (HLSDs), functional or technical specifications, sequence diagrams, and so on. They are generally made by architects, business analysts or developers and consumed by other architects, business analysts or developers.
This article is about internal documentation
For this article, I am going to be talking about internal documentation. Shipping documents for your customers should be part of your Definition of Done (if you are producing user documentation). There is no excuse for not doing it if you are supposed to be doing it. I don’t know of anyone accusing Agile projects of not producing user documentation.
The question is how well do they document their own systems from a technical perspective. A lot of people accuse Agile projects of not producing enough internal documentation, however. That is what I am going to discuss here. I believe that:
- Many Waterfall projects produce too much documentation
- Some agile projects produce not enough documentation
- The best way to produce documentation is “just enough, just in time”
- Choose information radiators over information refrigerators.
Waterfall projects produce too much documentation
I’ve worked on a whole bunch of Waterfall projects, in a former life as a business analyst. Crazy times. Everyone would spend weeks writing giant volumes of documentation before anyone built anything.
First up would be the business case, followed quickly by your Business Solutions Requirements document, usually a big beast, followed quickly by the ominous HLSD (High-Level Solution Design). Which an architect would pour their blood, sweat, and tears into.
Once someone signed them off (and we love signing off documents right?), then a small army of managers and analysts would produce a vast array of documents.
Project management plans, solution delivery plans, infrastructure designs, functional specifications, technical specifications, data transformation specifications, and a hundred others. Each of these could be anywhere from a dozen to a hundred or more pages.
These documents were generally linked to various phase gates, where the project could not move through to a certain “phase” until all the relevant documents were created, reviewed and approved. Nobody could really start work on their part of the project until the relevant documents had been approved either (which led to some major bottlenecks).
What were all these waterfall documents for?
These documents were all very detailed and had a huge amount of duplication. There were requirements in the Business Solution Requirements document that was more or less duplicated in the Functional Overview Specification documents, which were more or less duplicated in the Functional Specification document (with slightly different levels of detail). The main purpose of these documents was to try and:
- Prevent change
- Reduce ambiguity.
I’ve argued elsewhere that signoffs don’t really prevent change, and we sometimes don’t want to allow change anyway. But remember, agile says we should embrace change (my caveat is that we should as long as we are changing for the right reasons).
So what about reducing ambiguity? This is certainly a good thing, and it reduces “defect by specification”. That’s where something is built so that it actually matches the specification, but it is defective because what it does isn’t what anyone wants it to do. That is, it was a bad or unclear specification.
But the best way to reduce ambiguity is by getting people to have a conversation, not by writing a 50-page document. Why?
- conversations build a common understanding between people
- conversations are a better way to get people to remember things
- they can bring out details that the specifier might not have thought of, via questions and answers.
Of course, there’s nothing wrong with documenting a software system as you are building it. We just have to remember to have the conversations too. And I just don’t think that giant specification documents are the best way of documenting a system’s behaviour.
Some Agile projects produce not enough documentation
Let’s all put our hands up if you were on an agile project and you did not produce enough documentation.
Maybe enough for you, maybe enough for your team-mates. But enough for the poor team who has to maintain this thing in a couple of years? Enough for the consultants doing an R&D audit? Enough for an operations engineer trying to fix a production incident at 3am? Probably not. Let’s all admit that it has happened once or twice, and move on.
Some Agile projects just go too far. “We don’t have to write or read specs? Woo! Let’s just start building stuff and maybe somebody else can write something down later!”. It happens.
But we all need to remember not just the part of the Agile manifesto that says “we value working software over comprehensive documentation”, but also the bit just below that. “While there is value in the items on the right, we value the items on the left more”. We do need documentation, just not piles and piles of it. Well, how much then?
The best way is to produce “just enough documentation, just in time”
In a perfect world, we would all produce the right amount of (the right kind of) documentation. Producing the right amount of documentation, and the right kind of documentation, for the right people, at the right place and time, is hard.
It’s really hard. If anyone has the secret, please let me know.
A wise agile coach once told me that the objective is to produce “just enough documentation. Not too much, not too little, just enough”. You can also apply the Lean concepts of Just In Time production and deferring commitment. So you delay producing your documentation until the last possible minute, rather than producing huge volumes of it before any work is done. Why?
- documentation that has been produced but is not being consumed is a form of waste (the “inventory” type of waste in Lean)
- documentation can become extra wasteful if it is produced before a system is built and then the system changes so that the documentation is incorrect (the “rework” type of waste in Lean).
So you should produce documentation you are building a system, not before or after. Some say the best form of documentation of a system is the system itself. In the form of the code, the code comments, and the suite of tests that form part of the code. But that is a story for another day.
The final consideration is around how to store and communicate documentation. In a radiator, not a fridge.
Choose information radiators over information refrigerators
Is there room in that fridge for this HLSD?
Some people draw a distinction between information “radiators”, that actively push out information, over information “refrigerators”, that consign information to a cold and lonely death. What these terms mean may vary depending on where you work and what tools and systems that exist there. But think about it this way.
Is the documentation you are working on easily accessible, easily visible, stored in an open format (preferably HTML)? Do people use it often? Or did someone lock it away in some proprietary tool in a proprietary format? And it is difficult to even discover that it exists?
This should tell you which type you are storing your information in. Try to make sure your documents live in a radiator. In the hope that they will someday see the light of day and be useful to someone.
