Heineken's Documentation Principle
or, On Two Kinds of Documentation
I was thinking about software documentation the other day, at work. Documentation, as you may know, is the thing Agile Software folks care a wee about, just not as much as, say, the really important stuff like working systems and impressive stack of unit tests. This was in the context of actually considering of writing some more of said documentation. This contemplation remained as an abstract exercise (as is usually the case) without degenerating into actual physical documentation process, but it resulted in an observation: it occured to me that most documentation that I have written (or am about to write) falls neatly into two general categories:
- Documentation I have yet to write, that exists in my head, is fully up-to-date, and would be very useful if only it was written down
- Documentation I have actually written down, which is generally incomplete and out-of-date
Of these, the first category is obviously much larger than the second one. Nonetheless, all other documentation combined would be a mere fraction of the second category, and hence not worth further analysing.
This observation lead to the actual revelation: similar to the way Heisenberg's whatchamacallit (or was it this one?) states that the act of observation itself interferes with the (quantum) state of matter/energy, is it not also the case that the act of writing down of information as documentation renders it immediately obsolete? How else can it be that everything I write down becomes obsolete; yet everything I do not is (and remains) crystal clear in my mind, ready to be written down at a later point of convenience.
Having thus established an important principle in the field of software development, I feel that I can also try naming this principle. As much as it would seem prudent to name it along the more famous uncertainty principle, my ego demands something else. So let's hear it for "Tatu's Exclusion Principle" (analog to Pauli's EP):
"There exists only two kinds of software documentation: one that is up-to-date and useful, but not yet written down; and another that has been written down and is now utterly out-of-date and generally of little use"
... thank you, thank you, I will be here all week! Please don't forget to click the banne... I mean, tip the waitresses!
