Tortoise: Hello Achilles, what are you up to?
Achilles: I’m walking to Crete; I've heard it’s very beautiful in the summer. Have you ever been there?
Tortoise: No I haven’t, but I heard it’s a very long walk; it could take you months, and what happens if you get lost?
Achilles: Oh, don’t worry. You see I’m drawing this map so that I won’t get lost.
Tortoise (looking a little confused): I must admit to being a little confused. I thought that you’ve never been to Crete.
Achilles: No, but I’ll be there in two weeks.
Tortoise (now looking baffled): Achilles, if you’ve never been there before how can you tell me how long it’ll take to get there?
Achilles: We’ll I know that I’ll be there in two weeks, because that’s when I have to be there.
Tortoise: But if you have to be there in two weeks, shouldn’t you start out now?
Achilles: Yes, but I need a map first. Remember, I’ve never been there before; I’d get lost without a map.
Tortoise (speaking slowly): But if you don’t know the countryside between here and Crete how do you know what goes on the map?
Achilles: Don’t be silly, Tortoise, of course I don’t know what goes on the map. But a friendly looking guy came past the other day and I asked him if he knew the way to Crete. It cost me half of my gold just to get him to describe the major landmarks.
Tortoise: So, you know where you want to be, and you know the major landmarks well enough to write them down. Right?
Tortoise: And you think that you can compress the journey into two weeks?
Tortoise: Did the friendly bloke tell you how long he thought that it would take you to get to Crete?
Achilles: Yes, he said that it should take about two months.
Tortoise: And you don’t believe him?
Achilles: No. It may have taken him two months, but I’m built of sterner stuff. I can walk twice as fast as most men, and besides, I’m taking some short cuts …
It might help if I explain that you are Achilles, I’m the tortoise, the map is your project documentation, the fortnight is your estimate, two months is reality and the stranger with all the gold is a consultant. ‘Nuf said.
The most important thing in software development is the documentation, right? I mean, it has to be. We write so much of it, so it has to be important. That is why we take the most expensive and highly trained body of people in our organisation and ask them to write so much of it.
The only problem is that some teams have recently been reporting higher productivity, higher quality and higher staff satisfaction without having written a page of documentation.
But, if we don’t write documentation how do we know that the design is right, you can’t suggest that these people write code without a design?
I’ve heard that they treat design as a verb. I’ve heard that design isn’t the same as a document. That design is a thought tool and a communication tool. And once that tool has done its job we don’t really need to document the results.
Next week's column will be an XP conference special. I’ll be speaking at the conference and will bring back interesting tales. The conference is in Auckland; see my website for details.