IT Commandment: Thou shalt document all thy works
Summary: If you don't, your selfishly undocumented software will rapidly fall into disuse, a neglected monument to your wasted effort.
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:
- Thou shalt not outsource mission critical functions
- Thou shalt not pretend
- Thou shalt honor and empower thy (Unix) sysadmins
- Thou shalt leave the ideology to someone else
- Thou shalt not condemn departments doing their own IT
- Thou shalt put thy users first, above all else
- Thou shalt give something back to the community
- Thou shalt not use nonsecure protocols on thy network
- Thou shalt free thy content
- Thou shalt not ignore security risks when choosing platforms
- Thou shalt not fear change
- Thou shalt document all thy works
- Thou shalt loosely couple
Kick off your day with ZDNet's daily email newsletter. It's the freshest tech news and opinion, served hot. Get it.
Talkback
I rarely agree with you
Yeah, right.
1) A database of functions
2) Good communication
3) Developers that will check the database FIRST
Software Engineering requires:
1) Documentation (Data dictionary, Project Spec.)
2) Standard methodology
You CAN do one without the other - but you really need both to make a difference. JUST documenting thy works is a step in the right direction, but if not followed up - is a step to nowhere.
I'm sure there are many great software components
The mentality of a programmer
Hardly Document?
Why not document everything?
Requirements and design documents are typically "first drafts" of a project, in my experience. They quickly go out of date, because no one, not even management, wants us to take time to go back and continually update it. Likewise with scheduled software projects, the emphasis is on keeping the cost low. So there's pressure to keep out activities that are "non-essential", lest the customer has to pay more for it. If anyone were to ask me whether keeping documentation was essential, and take me seriously, I would say yes. The thing is, management typically does not understand this. To them, productive work is working on code. That's moving the project forward, and they like that.
I have to say in these situations in-code documentation is just not highly valued. I mean, the customer is hardly ever going to see it, and they're the ones paying for the project. I make an effort to document code that I think will be reused, or is unusual/esoteric in nature, but that's because I have a streak of altuism. I agree, someone's going to have to maintain it later, so they need to understand it, but asking me to do a complete job for everything is asking too much of me in these situations.
Customers do like seeing requirements and design docs., so we produce those, but typically "design" means "what do the screens look like?", not control or data flows, not use cases, and certainly not class hierarchies. But like I said, once those docs. are signed off on, they quickly go out of date, because the customer changes their mind during the project. It always happens. From what I've seen, they haven't wanted to sign off on another version of the requirements and design docs. every time they change their mind. It's just assumed that the docs. are amended with change requests. And by the way, make a practice of getting ALL change requests IN WRITING: e-mail or Fax. Customers have a nasty habit of forgetting that they asked for something to be changed.
Typically if the developers discuss things like use cases or class design, they do it on a whiteboard, which after discussion gets erased. One technique I've heard about is to take Polaroids or snapshots with a digital camera of the whiteboard before it's erased, and then put them in with the other design documents as amendments. It's not clean, but it's efficient for getting back to work, because nobody's going to sit down and formally edit/document what's been discussed. Development groups are not given the time for that.
So, documentation ends up being a hodge-podge at best. Developers just have to deal with that.
I've always found it interesting....
Agreed, but...
Another problem is that management may not value documentation enough and is therefore not demanding that it be a part of the project deliverables. But this hardly ever happens, right? None of us know managers that are clueless about software, right? None would ever say that getting it into production yesterday is better than making it right for tomorrow, right? None would ever make the mistake of assuming that the costs of an application stop at initial rollout and fail to consider the continued maintenance costs for the rest of the software's life, right?
Too much documentation may not seem like a problem in most shops, but I think Scott Ambler's Agile Documentation philosophy makes a good point. He feels documentation should be enough to explain what a good developer needs to know, and no more. Heavy documentation can be so overbearing that it takes forever to write and read, becomes outdated, and becomes itself a maintenance hassle to keep up to date. The tricky part is figuring out that place between [b]enough[/b] and [b]too much[/b].
Ditto
You have no idea :)
My immediate supervisor was named Steve. Steve was the ultimate "get it out the door ASAP, I don't care what it looks like" kind of programmer.
I remember my shock the day he took me aside and told me "You comment too much, I don't like it."
However I refused to reduce my commenting level and a few months later I was in a meeting where two others starting complaining about how difficult it was to modify programs in Steve's project.
I think I managed to keep my grin down to a polite level...