Sunday, April 27, 2008

It's much more than throwing out the documents

I was talking to a fellow Ab Initio developer the other day and he asked me a common question...

“Isn't all this Agile stuff just a case of not writing documentation?”

It's true that Agile teams do less documentation, but it is always replaced with better alternatives. I'll put that another way because it is important. Agilists do not throw away documents for the sake of it - that would be a pointless short term fix - but we are passionate about reducing waste in our projects and we have found there are more effective ways of doing some things that every project needs and they happen not to need as much documentation. (Mary and Tom Poppendieck showed us how to use Lean principles to identify and eliminate waste in software projects, this interview is a great place to start.)

This can be a little difficult to imagine if you are used to waterfall projects, so let's look at a couple of typical activities on data projects and the practices we can use to do them more effectively and reduce the documentation overhead.

Test Procedures

Waterfall teams write test procedures to record the manual tests that need to run against each release. There are problems with this approach: the tests take a long time to run manually, they are subject to human error, and because natural language is imprecise and ambiguous technical details gets lost in translation by the tester.

Agile teams use Test Driven Development and executable specifications to create automated test environments that can be run quickly and easily by anyone on the project (including stakeholders). Automated tests are absolutely precise – they either pass or they fail, and if a bug occurs you can simply add a new test and that error can never happen again.

Requirements and design

In Waterfall, business analysts use requirements documents to capture what the customer needs, then the designers create another document that interprets the requirements in technical language. Again, there are two problems with this. It takes a long time, so requirements go out of date and because natural language is subject to human interpretation the customer's original need gets lost in translation.

Agile teams are cross functional including business analysts, designers, developers and testers all of whom engage directly with an empowered representative from the business. They work in short iterations of a month or less that deliver solutions to the most pressing business need at that time. There's no need to maintain detailed requirements definitions or design specs because the customer is able to communicate what is needed face to face and the tests accurately describe what the code does.

Requirements traceability comes for free because Agile teams never let requirements and code diverge. Put another way, the V model, never opens out into a V.

Change Control and Risk Logs

Honestly, does anyone enjoy working through these?

Requirements and designs go out of date on waterfall projects, so they need a whole extra level of documentation and bureaucracy to track changes and uncertainty.

Agile teams simply do not need any of this stuff because they are always working on immediate priorities and the chunks of work are small enough that they can actively address risks early in each iteration.

Look for the Principles

Of course, I have really just scratched the surface, but if we look for the principles behind the practices we find ways to improve our thought processes.

Documentation is a legitimate form of knowledge capture, but it's not always the best option. There are times when documents are necessary and useful, recording business metadata is an example that springs to mind, but next time someone asks you or your team to write a document, recognise it's a default position – the lowest common denominator of project communication – and everyone involved might find a better way of working if they were to kick the problem around for a while to address the root problem more effectively. Sometimes you will find a document is the best solution and other times you will not. In either case, you will reach a well considered decision based on a reality.


Vertue said...

What is interesting however is the assumption that the documentation on tests, risks and requirements are waste though. What if you can show that they do add value? For instance in many regulated environments those document provide assurance to the regulators that you have mitigated the risks, tested the important stuff and met the regulatory requirements. Also the documents are readable by most whereas the code and tests aren't always.

Ron M said...

Don't confuse throwing out documents with throwing out documentation (i.e., information). What if an executable specification happened to describe a risk mitigation. And what if the executable specification was indeed readable by most. It's quite possible to do this using FIT or FitNesse. The result is a single virtual artifact that documents the risk, the mitigation strategy, and the effectiveness of the mitigation. Furthermore, this eliminates the wasteful practice of early baselining the software to insure a mitigation hasn't been compromised when the software is changed - instead you just add the mitigation tests to the regression suite.

Agile is not about avoiding important things. It's about accomplishing that which is important in a leaner, and often far superior way.

Anonymous said...

If the code and tests aren't readable, it's better to work on making them more readable before deciding to maintain two sets of parallel specifications.

Especially for code, ideally, the specification is the code. This can often be done for certain areas of the program by creating a DSL.

If you documents for regulatory purposes, well, that's fair enough, but these then become part of the output of the system that produces your product. And, ideally, if something other than the document actually implements the regulatory constraints, you should try to generate the document from that (or vice versa, if that's easier).