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!
