Documentation and Agile

Today I saw a question on the LinkedIn Agile forum:

Where do you go to see what the code "really" does besides asking a developer?

What I worry about are where are the final documents that describe what the software does? That seems to get lost in Agile. And is sooooo important for long term maintenance, Technical Support/Call Center and years later Product Owner updates.

There are all kinds of assumptions and world-views wrapped up in this, including the old bugbear "we're Agile, so we don't need documentation", which not only is plainly invalidated by the Agile Manifesto but is quite clear for everyone that understands the principles and values upon which Agile is built. Documentation has value, but it also has cost. Where there is no better way of doing something, we will create documentation, but where there is a higher benefit-to-cost ratio option, we will use that instead.

The original poster's question above needs Root-Cause Analysis - example: why do you need documentation? Could it be because:

a) I am a new guy and I want to learn how the system works?
b) I am a customer service person and I want to evaluate whether what the customer is describing is a bug or the way the system normally works, so that I can close the case?
c) I am a support triage manager and I want to rate this case as a defect or a change request or WAD ('Working As Designed') so that I can send it to the appropriate team?
d) I am a Product Manager and I want to know what the system was specified to do so that I can construct a product roadmap?

All of these answers embody one or more organisational dysfunctions:

a) You need an on-boarding programme with proper training and mentoring; just sitting the poor guy down with a user manual is not the answer to making new staff effective quickly.
b) CSMs shouldn't be closing cases as WAD/"Not a bug"/whatever - the role of the CSM is to make the customer happy, and this means understanding what the customer's issue is and following through. Telling them that the way that they interpret the manual sitting on their desk is that "this is the way the software is supposed to work" isn't helping the customer. Gain understanding, formulate a plan of action with others, execute that plan and monitor and follow-through with the results. CSMs should 'own' the customer experience.
c) Different silo-d teams handling defects vs. change requests is a 'team smell'. People closing customer issues because the software is WAD is a process and a team smell. Actually having so many product issues that you need a support triage manager is an 'everything' smell!
d) If the Product Manager doesn't know what their product should do, God help you all! (Hint: satisfying the customer is a good start). As DHH said: you don't need an issue tracking system to tell you what is wrong with the product, you just need to listen to your customers, because they will tell you *every day* until it's fixed!

Going back to the original question: "How do I know what the software does if I don't have any documentation?"

1. If you want to know what the software does - actually use the system. 'Normal' behaviour is quite obvious to a regular customer.
2. If you want to know what customers want the system to do, simply ask people that field customer support calls (which should include your entire team on rotation at least once a month, everybody, no exceptions, even your execs). Quite frankly, it is irrelevant what someone specified the system to do X months or even years ago - whether it was a Product Manager or your customers - if none of your customers actually want the system to work like that now...

If you want documentation as contracts, then automated tests (acceptance, unit, integration, etc.) are the best solution, as every build has to fulfil these contracts. The works of Dan North and Gojko Adzic are valuable starting points here. Next stop, the code. If neither your tests or your code are readable, you have a larger problem than not having a specification document!

The problem with written documentation that isn't executable i.e. tests or code, is that it quickly becomes out-of-sync with the product as it has little or no value add over the tests and code to the people actually writing it and it is not possible to automatically verify that the document is wrong because there is no automated method of validating the documents against the actual product. As a consequence simple human nature steps in; we are lazy forgetful creatures that don't like duplicating work we've already done. Result: the documentation is always a lie; as time progresses, the lie gets larger. Behaviour-Driven Design (BDD) or its child Specification By Example (SBE) can really help here.

In the past the documentation has been the contract between the customer and the supplier, between the marketing function and the IT function, between the development team and the support team, between the architecture team and the development team, between the development team and the operations team... The Agile way of working is to shift the emphasis away from contracts and towards working software as the primary metric of success, and to minimise contracts as mechanisms for limiting change and to shift to a new way of working based upon collaboration and prioritising change effectively.

This fundamental change in the way of working makes people who are used to working with written contracts all their life uncomfortable. Many people don't like change, many organisations don't like change. Agile isn't for everyone, and it isn't a silver bullet. Don't feel that you have to 'embrace Agile' if your organisation is not on-board with this kind of radical organisational change management programme.

For those that are committed to this kind of change, the rules of Simple Design, good Stories and acceptance criteria, and SBE/BDD (with their associated TDD and CI) are an excellent place to start with making the code and tests better fulfil the functions previously taken by documentation.