"Working software over comprehensive documentation.", The Agile Manifesto, 2001.
Agile documentation is not exactly the most clear cut subject in the community? How much documentation should we create? What works? What doesn't? How do we transform from a traditional process to an agile one with regards to documents? This is an area that lacks clarity in the agile community.
A recent blog entry on Zen Agile asks the question "How Much Documentation is Enough?". The writer talks about his experience with government agencies and the reasons behind their very document-heavy processes:
It’s been suggested to me that all of this documentation is required “because we’re government”. When probing a little more I’ve generally found the following reasons are given:
The business needs comprehensive information to sign-off and approve the build Developers need to know what the system is designed to do Other developers need to know how the system was built in order to do improvements Other developers need to know how the system was built in order to do maintenance The government requires sufficient information in order to know why money was spent and how it was spent In my experience, however, very few people in the business understand requirements documentation. They tend to read through the project background to make sure the current state and rationale for the project is clearly articulated, they might go through the business process maps because as a graphical depiction of the project it’s easier to understand than a use case. But overall, getting them to sign-off and approve something they’ve not seen is a bit … well … it’s just not logical.
The blog then goes onto report an alternative for documentation that consists of:
- Articulating the context via personnas, scenarios and context diagrams,
- describing the requirements with process maps, and tracability matrices,
- documenting the solution with data models, site maps, navagation design, and UI design,
- validating the solution via prototypes, signoff happens here, iteratively, and
- documenting the system build which includes code, testing regime, and physical data model.
This above process has been thought out and comes from experience. But is it anything close to what we all do in the community?
There are conversations about stories, use cases, and tests as specification. But is that all there is? There is a full book on Agile Documentation that this reporter had never heard of until researching this topic. There is a chapter in a book about evocative and representational docs. And there is even an InfoQ news article written over 3 years ago on the subject.
Do we have a consensus or even a few cohesive 'schools of thought' when it comes to documentation? It is really difficult to tell because so little is written on the subject. Maybe the subject is just too simple to write about. Or maybe it is too complex and we really don't have a good idea what to recommend. Thoughts, good reader?
Community comments
Agile is just used as another tool
by Markus W.,
Re: Agile is just used as another tool
by Keith Barlow,
Agile is just used as another tool
by Markus W.,
Your message is awaiting moderation. Thank you for participating in the discussion.
Sometimes I feel that Product Owners are too distracted (or too lazy) to be fully involved in the development even though this is the fundament of the product's success. For them agile is just another tool like jira. So their backdoor is in the documentation:
On one hand they can give account to customers and accountants about the project's progress and on the other they have a basis to be pedantic about variations which gives them the feeling to still have control of what's happening.
The general problem is that most of the time decision makers are untrained and therefore not fully aware of the concepts of an agile development process. Under pressure they are unable to use and trust the benefits and then automatically fall back to, for them, well known concepts they have learned 20 years ago: The power and knowledge is in the documentation.
Re: Agile is just used as another tool
by Keith Barlow,
Your message is awaiting moderation. Thank you for participating in the discussion.
Although the recommendations for documentational alternatives describe the types of documents that should be created, I think they also succeed at providing a better description of why documentation should be created than the original reasons quoted. Some of the primary purposes of documentation are not just description of requirements for hand off but also include cohesiveness and accountability (did the production match the request). The cruxes of producing the documentation also server as a way to examine the system model before any development is done. This is the backbone of systems engineering.
From an agile perspective... I think too much documentation often gets forsaken in the name of agility. It is completely true that production of documentation is a burdensome process that hinders the productivity rate of those looking to produce. However, as has been argued by more than one blogger, the origins of agile programming are in the ability to respond to changes in requirements, not increasing productivity at the cost of forgoing fundamental parts of the process. Documentation serves many valuable purposes and the need for exuberant amounts of documentation varies proportionately with project size (in my opinion). In many forums, it is quite easy to forsake documentation in favor of verbal communication which tends to be more natural and agile. However, inability to recall fundamental aspects and details surrounding a decision is something that may come back to haunt you in the long run as many cases have shown. It's a shame that producing documentation takes so much away from the ability to be productive; however, until better technologies exist... I fear this is going to be a question for some time to come.