At the end of his Tractatus Logico-Philosophicus, Wittgenstein has a famous quotation:
6.54 My propositions serve as elucidations in the following way: anyone who understands me eventually recognizes them as nonsensical, when he has used them – as steps – to climb up beyond them. (He must, so to speak, throw away the ladder after he has climbed up it.)
More or less, I feel the same way about technical documentation.
Sometimes, you will hear someone say that all you need when it comes to documentation is the code itself, but this is, obviously, silly. Besides the fact that project managers, business analysts, and others who need to have access to technical documentation generally can’t read the code itself, even if they could, they won’t (nothing about BDD solves this, BTW).
And even if they would or could read code, it wouldn’t solve the basic problem. As a developer/architect/whatever, when I come on to a client, I’m usually dealing with a codebase of significant enough size that it isn’t enough to just try to read the code. What is needed is some sort of high level document that explains how things work and why. I need to know *where* in the code to look and why.
The paradoxical nature of technical documentation comes out in different ways:
- The developer who doesn’t need it is the one who needs to write it, and knows it is technically obsolete the moment it is written.
- The developer who does need it doesn’t know how to write it, and once he understands it, doesn’t need it because he knows it was technically obsolete the moment it was written.
- The developer who needs to write it doesn’t have time to write it because it takes away from his immediate deliverables, even though he knows in the long run it will save him time.
- The manager who can’t or won’t read code insists that technical documents contain actual code, because he doesn’t understand how technical documentation is useful unless it contains code, even though the developer who doesn’t want to write it and the developer who has to read it don’t usually want to see actual code, because they know that any code included is obsolete the moment it is written (this is the one that really kills me…”I need any developer to be able to read this document and start coding”…um, 6 months ago, I would have wanted a document like this, and I wouldn’t have wanted code in it…”Yeah, but it has to have code in it, otherwise, how could a developer use it?”).
The idea is to find a happy medium of some sort, and the obvious solution to me is some sort of high-level overview of the system. Perhaps a piece of it would include specification type documentation that would be of most use the the BAs and PMs in the group, and another piece that would tell you how the system worked, and where in the system to look for the details.