The Paradox of Technical Documentation

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.
posted on Monday, April 05, 2010 9:01 PM Print
# re: The Paradox of Technical Documentation
4/6/2010 8:29 AM
I really like the idea of a reference architecture solution for this. I try and maintain a smaller, but still important, application which makes use of the underlying framework components in patterns in an accessible way. Sometimes this manifests as just keeping a specific area of a larger solution as clean as possible and using it for reference. Because the "documentation" is a working app, it doesn't feel like waste to maintain it.

You can get a long way with good unit test examples here too.
# re: The Paradox of Technical Documentation
4/6/2010 6:27 PM
That can work, but it is still too 'code-y' for me. Plus when you are working on something that involves, e.g. C# and Java and Oracle and SQL and MQ, it isn't something that you can build a reference app for easily.

A lot of difficulty I run into is when you are months into working on something and you discover that (to use a recent example) there the code you are working on has an external dependency on a file produced by that Unix Control-M job pulling from the mainframe, and your immediate reaction is: "WTF, there's a mainframe? Shouldn't someone have mentioned this?"

A good technical document would cover just this sort of thing.

Post Comment

Title *
Name *
Comment *  
Please add 1 and 2 and type the answer here: