IT Commandment: Thou shalt document all thy works

Reuse is at the heart of all today's hot IT trends: open source, SaaS, Web 2.0, mashups, etc. But how is anyone supposed to reuse a piece of code or a service if the documentation's inadequate? When I started out writing this commandment, it was headed "Thou shalt not reinvent the wheel". But then I realized why everyone always does: it's just too darn hard to do anything else.

Failure to document is thus one of the biggies of ZDNet's IT Commandments, high up in the mortal sin rankings with the likes of 'Thou shalt not kill'. For if you don't document your work, how is anyone else supposed to reuse any of it? From your greater sin flows a multitude of others' lesser transgressions.

And when I say 'document', I don't mean a few comments sprinkled here and there in the code for your own benefit (although frankly, that would be a start). Nor am I interested in a user manual that simply describes what the user already knows from looking at the application — and which no one, quite rightly, will bother to read. No, I'm talking about a veritable cornucopia of practical information: what the program does and how is just the start. Other people need to know what it was and wasn't designed for; how it performs and what the limitations are; how it's been tested and what the results were; along with a host of other things.

Documentation is the lifeblood of collaborative computing. If you don't know who else is going to share your program code and what they're going to use it for, you have to make everything within it crystal clear. If you're exposing a service interface rather than the underlying code, you have to provide even more information. Not just the information that pertains to how you yourself plan to use the service, but all the information that anyone would need to decide whether the service can be used for something you've never even thought of yourself.

Why bother? Because if you don't, your selfishly undocumented software will rapidly fall into disuse, a neglected monument to your wasted effort. It will never flourish as a vital component of applications you never imagined, enjoying a rewarding afterlife many years after its original purpose has faded into oblivion.

There is an IT heaven, and the stairway is paved with documentation.

---

Our IT Commandments:

1. Thou shalt not outsource mission critical functions
2. Thou shalt not pretend
3. Thou shalt honor and empower thy (Unix) sysadmins
4. Thou shalt leave the ideology to someone else
5. Thou shalt not condemn departments doing their own IT
6. Thou shalt put thy users first, above all else
7. Thou shalt give something back to the community
8. Thou shalt not use nonsecure protocols on thy network
9. Thou shalt free thy content
10. Thou shalt not ignore security risks when choosing platforms
11. Thou shalt not fear change
12. Thou shalt document all thy works
13. Thou shalt loosely couple