I allmost posted this to my SW-IMPROVE discussion list, but it’s a little bit too saracastic. I figured this audience could appreciate it a bit more for what it is, as a joke …
Engineering takes place when you leave behind artifacts that communicate your design decisions and intent at a higher level than source code. Engineering includes scaffolding and tooling and jigs: items that you use during construction, i.e. unit tests.
And I allmost replied:
Joe, let’s go back to physics for a minute. “Artifacts” add to mass. If it takes energy to move, more mass means that it’s more expensive to move. When you have big changes after the initial design (and you always do), you either have to go update the artifacts to make them current (expensive), or leave them be (potentially dangerous when the new hire trusts the “design documentation.”)
No, I’m not saying no documentation. I’m just advising documentation that is small, quick, and light. If you look at what I’ve been checking in for the past six months, for example, you see a lot more recorded .wav files and quicktime movies describing what I am about to build than word docs. I also write automated tests, which are an executable spec, and I agree with you on scaffolding.
To paraphrase Kent Beck, the few artifiacts that I do keep are small, light, and valuable.
Now, please, keep in mind, I’m not against artifacts. I’m not against a single thing that you said, actually – I’m just concerned that an inexperienced developer (or manager) will read a paragraph like that and miss all the little semnatic and contextual clues that come from being a skilled craftsman, and say something like:
“For software engineering to be a true engineering discipline, we need to generate artifacts … “
blah blah blah. Gag me with a spoon.
And now, If you’ll excuse me … I gotta go code …