My friend Jim says, “Have to say, if I were a customer I would stipulate that you left me documentation. I wouldn’t buy services from a company that didn’t ;-)”
One of the responsibilities of an Agile Coach (or perhaps this the role of a ‘Business Coach’ or ‘Client Principal’ – but a role isn’t the same as a person) is to find out what it is that the customer really wants. In the example I gave, it’s maintainability, not documentation. If documentation is the only way to provide maintainability – for instance, if the customer hasn’t been able to provide any in-house staff for pairing on the project – I might suggest writing it in the weeks before handover, so that it’s accurate and up-to-date. There’s no point doing this as you go along in Agile, because you know that the customer requirements, the application and therefore any processes / documentation are subject to rapid and frequent change. A pragmatist might document the more stable aspects of the project, such as architecture or persistence mechanisms, but even they’ve changed during the lifecycle of the project I’m on.
Another reason why customers like to see documentation is because it gives them some idea of how the project is going. Agile development provides other ways of measuring this. Most particularly, the customer can see progress in the number of stories (requirements) implemented, and by sitting down and playing with their new toy as it evolves.
Some projects may not be suitable for Agile development (mission critical?). Even so, I bet my lunch that there are still Agile practices which can improve the quality and speed of code production.
When someone wants something that doesn’t make sense to me, I usually ask, “Why?” Sometimes it helps that person clarify what they really mean, and sometimes I learn something new from the answer. It’s always a fun question to ask, and often the most important one.
Liz Keogh, lunivore 
Why do I want docs? Lots of reasons really.
In principle I like the idea that you train up someone to know what’s going on. In practice I can see things getting missed. You then have the problem that that person has the knowledge – if they are ill, have an accident, etc you’re screwed (or it costs you to call the company back and train someone else). If you have docs that are well written and well maintained this is certainly less of a problem.
Its not just about ‘knowledge backup’ either. Most projects are WAY too big for a single person to keep the info in their head without some form of notes – why not make them formal docs?
Lastly, the very act of documentation causes me personally to think about what I’m doing. Often, as I’m writing an explanation of something own I’ll reread it and realise that there’s a better way of doing something.
From a customer’s PoV it also allows them to have a kind of milestone that they can see and touch before they sign off on the project.
Again – I’m assuming the docs are well-written and relevant. Bad docs are worse than useless in many cases but that doesn’t mean we should get rid of docs altogether – some people fuck up using pointers but lots of people still use C 😉
Hi Liz,
A couple of triggers.
First off, regarding “why”, I’m not sure if you’ve seen Dale Emery’s website ? He writes about what he calls “The Value Question”. I think you might enjoy it. : http://www.dhemery.com/cwd/2003/06/the_value_question.html
Secondly, on the subject of documentation, my response is usually “stick it on a card”. User Stories are, informally, “Stuff the Customer wants the techies to do”. One of those things can be documentation. Give it an estimate, let the customer schedule it, make them aware that (like Internationalisation) the estimate could change depending on when the story is scheduled. For another perspective, see : http://www.xprogramming.com/xpmag/expDocumentationInXp.htm
A.
I guess the need for documentation is reduced by Agile’s ideals of clean, legible code. We had a big discussion here about the maintainability of highly OO patterned designs. Some of us have suggested that ‘ideal’ OO code is less easy to read and maintain, but I think that once I got my head round some of the ideas – eg: dependency injection – it wasn’t so bad for me.
Have you tried doing Test Driven Design? I think it plays the same role of clarification as your documentation does, and the tests also help ‘document’ the project by showing what each bit of code should do. If you ever fancy reading up on it, I’ve got half the TW recommended reading list at home; will be happy to lend something next time I’m down your way. I don’t know how much you know about Agile already.
Agile milestones are working software releases, ideally at about one a week. Makes it very hard to hide a lack of progress. There’s a transparency in Agile that highly documented, traditional top-down development can’t match.
This project’s been going for three years, and most of the guys here will admit that it’s a bit of a mess. I can’t imagine any way in which formal documentation will help, though. There are tests for pretty much all the code; the architecture is standard (and I need to read up more to understand it better); and the in-house guys we’ve been pairing with are writing instruction manuals for the end-users. Very few of the people here were here when I joined four months ago, but we’re all getting along just fine. Somehow, even the limited application of Agile here has just… worked. It’s just magic.
That’s a good idea. I think it’s important for a customer to realise the actual value of any documentation, though, given that some Agile practices cover the same ground as documentation anyway.
Devs like me don’t like pointless activities, and mostly I hate writing documentation beyond a code comment or two. I much prefer to sit around for half an hour working out what I should name that method, or whether this particular class shouldn’t delegate some of its responsibilities elsewhere. If I can persuade the customer to let me do that, I’m going to be a happier dev. I guess maybe being an Agile Coach is just a balancing act between the money and the fun.
I read Dale’s post. The Value Question is “Why?” with more focus, which is fair; I tend to ask “Why?” about everything, including clouds, religion, eating fresh fruit and playing close to cliff edges. “Why” without limits is fun, but doesn’t actually help me get any work done.
Clean, readable code is where everyone should be heading – Agile or not. Docs aren’t there to allow you to write bad code 😉
At BIDS we had to write test harnesses for every API. Each test harness was written from the documentation of the function it was written by someone who hadn’t written the function. You’d then run the tests and see if the function did as advertised and if not either the code or the docs were wrong.
If you don’t have some description of the function somewhere, then the function itself is the reference point. If the function doesn’t do as it is supposed to how is someone a year, five years, ten years down the line meant to know that?
I’m reminded of a comment Professor Fitch once made: Ideal code should have no comments or documentation – that way you have to read the code to find out what it really does… He wasn’t being 100% serious 😉
I’d love to make you my Agile Coaching guinea-pig some time. New Blog post on Test Driven Design in lieu of documentation is up…
Elizabeth,
Perhaps a better idea than writing all the documentation at the end is to write documentation as you go, but generate it from the code as much as possible.
I was writing out my views on this point, and it turned into too much of a rant, so I’ve posted it on my blog.
http://www.mattryall.net/article.cgi?id=186
Matt Ryall
Thanks, Matt; there are some useful thoughts there.
I especially like the idea of automating documentation updates. There has to be a way in which something like a Wiki could be used for this. Could maybe change the build process to include warnings of broken links, out-of-date information, etc.?
One of the problems I’ve noticed with Agile is that all the ‘working’ bits of the system – the stable stuff which doesn’t get changed – also doesn’t get much pair time. Knowledge is slipping away, there.