Here are reasons why we need bureaucratic documentation even though not everyone is really convinced! Each section applies at all levels of documentation and the same basic points about human nature and the human condition keep coming back. It's worth thinking about the role all these ideas have to play in maximising our profit: making sure the customer wants to pay us for the work we actually end up doing.
This very document is supposed to be an example of what it says. I'm trying to work out for myself, and tell everyone else, what I think the quality docs are for so that we can design them to be maximally effective and minimally intrusive.
Communication.
Everything about a project, from its aims to the details of the implementation, must be made as explicit as possible. Experience shows that otherwise, inevitably, there will be mismatches between ...
what we think it is for --- what the customer thinks it is for
This is the most disastrous kind of misunderstanding because you end up doing the wrong work right from the start. Afterwards customers are not forgiving ("oops, I should have told you") but resentful, even if it is really their fault for not actually knowing why they want the product.
what the various parties think their role in the project is
Witness Iglu's and APR's role in iglu.com (I'm not saying it mattered much)
what developers and other workers think about the system outside their own immediate area
The very best project leader cannot be expected to keep everyone informed of everything they need to know. I have never yet failed to waste time on a project through not knowing everything, but this effect was noticeably lessened under ISO 9002 where everything was (supposedly) written down.
It's necessary to write it down in a way which is structured in both an abstract sense, so that people know where to find things and you don't leave things out (it's inevitable), and narratively, so that people can actually understand it---not least, the customer.
When you write something down it becomes much easier to stick to it. This applies both to the overall deliverables and to the myriad micro-``contracts'' involved in programming (even on your own): there is a definite point at which you say ``this code does such-and-such and it really works''.
You can't actually make everything explicit, it changes, it all takes time, and so on. But you don't have to get it 100% right. Each 10% you do get right will save you a lot of trouble. 90% is a good target.
It's impossible to get something right first time. It's impossible to get something right second time unless you think about it first.
The number two management mistake is failing to think ahead a little. (The number one mistake is allowing miscommunication and misunderstanding to flourish; see ``make it explicit''.)
To decide what you really want, bring out hidden assumptions, thrash out what it has to do and how it should work, expose the banana skins, there is no alternative: write it down. Otherwise it's terribly easy to go on thinking you know what you are doing---right up to point at which you discover that you aren't.
Now, you can't actually do this---perhaps you can only get it 30% right---but even that will save you a lot of trouble.
A properly organised set of project documents will naturally make it explicit why everything is being done, at every level from the immediate cause and authorisation to the business goal. This is reassuring for the customer but also genuinely helps to keep everyone focused on things that really want doing.
This really applies to micro-level things like code changes.
Guess what, you get an audit trail. If the system turns out to be broken it's a big help to know what was actually done at various points in the past---and whether they can safely be undone, what changes go with what, and so on.
A code base which is not documented and, more importantly, organised into a living project, is like a business with no proper paperwork where it's all in the boss's head. Its value to an incomer has to be heavily discounted because they must to get into it. Even if we simply want to pass maintenance of projects around between Paneris members it's essential to have a ``corporate memory'' of each.
Proper documentation makes a hugely positive impression on customers. It also makes the developers feel they really know WTF is going on, and that they have this beast under control---so it keeps up morale.
Document Dated: Sun Nov 08 1998
Modify this document
Previous Version