Common practice says that software projects need documentation. But there's still something of a gap between the preaching and the practice. In small companies especially, managers may claim there isn't time to document, or that "Our project is different." Maybe some of these managers know something the rest of us don't know. Are there factors that might make a project exempt from documentation? I've thought of a few possibilities.
Don't Document if your People will never Change
Your company is so wonderful to work for that you know the people in it will be there forever. Employees will never leave for different jobs in other companies-or even for different jobs within your company, since employees who work entirely out of their heads can't be safely promoted. You'll never have to lay off or fire anyone-or anyone whose job isn't too simple to need documentation at all. Your workers will adore their jobs so much that they'll arrange their lives around the company. They'll never move away, go back to school, have babies, or even take extended time off. They will also never have accidents or long-term health problems, and they can be completely guaranteed to live forever. Who says you can't run a business out of people's heads? You can, as long as those heads will always be there. As long as you don't have to employ normal humans, you should be fine.
Don't Document a Product that will never Change
It's safe to avoid documenting software that will never need a single change, or a single fix. Your customers will love it forever just as it is, and it will never need maintenance of any kind. It can be installed, deployed, and run by anyone: even a computer-illiterate with a two-figure IQ won't have to ask a single question. This is the perfect paperless program-it doesn't even need any pixels except for its own. This is going to be a spiffy 1.0!
Don't Document if your Product Is Vaporware
Let's face it, a product that never truly exists doesn't need documentation, since nobody will ever need to know anything about it. Why document code that never leaves the developers' machines, and maybe doesn't run there either? Maybe it doesn't even compile-in which case nobody has to learn how to build it. And if it never enters test, no test group needs to know how it works. No one will ever need written instructions about how to install or deploy it, and customers won't need help figuring out what never ships. The nonexistent product doesn't need documenting any more than the nonexistent naked emperor needs clothes. An undocumented product lives only in hearsay, and everything is much tidier if the programming is hearsay too. Companies that are too theoretical to produce a product won't be dinged for failing to document it properly.
Managers who skip documentation don't seem to be expecting either perfection or failure-at least consciously. Mostly they're trying to save time, and assume that hackers' methodology is the way to do that. These managers expect that complex technical communication will just happen-that unscheduled meetings in the hallway can produce a well-designed system. Hallway meetings can be creative and productive, but they've never been enough: not even when software was small enough to fit on a floppy. Software that spreads across gigabytes of real estate on multiple machines can't possibly be thought through in the oral tradition.
If you don't ride herd on it in writing, the best you can produce is misunderstanding, excessive bugs, and headaches-and the worst is an unmaintainable release or no release at all. And hallways are likely to include only developers: other technical employees who need to understand the product so they can test/deploy/support it may not even be hired yet. And what about the next generation of developers who need to change or fix it? I don't see how a company can be in control of its technology without writing it down. Even bare-bones start-ups need a paper trail of some kind.
You have to preserve enough talk so you can keep track of what you're doing. Most developers I've worked with have been willing enough to talk about their work. But few are willing to write about it. Many developers don't see writing as work-or at least they don't see it as their work. But an even greater problem is that they don't see writing as talk. The audience isn't present, and can only "hear" it later by reading: but it has to be talk, or it's useless.
Lately I've been seeing start-ups that have come up with something worse than the undocumented system; that is, the overdocumented system. These situations tend to come about when managers, usually technically challenged ones, turn documentation into a form of punishment, and install an inappropriately complicated document control system to enforce it. These systems are dauntingly difficult to understand and maintain, and a shop that's under-resourced already can't be expected to do either. Documents in these companies are done in place of work: they're not communication, they're just filler. Everybody has to write something, but nobody has time to read anything-which is just as well, because everything is hard to find. You can fill TechSpec.doc with source code and no one may ever find out. This documentation isn't supposed to say anything. It's just a micromanagement tool for an overcontrolling boss, so employee passive resistance against this busy work is inevitable.
Overdocumentation makes documentation meaningless, and I think meaninglessness, in some form or another, is what has given documentation a bad name. Technical docs are supposed to be a record of clear thought, easily used by others. They should say something real about the technology to somebody who needs to know. This is real work, and even the leanest start-up needs it to keep enough so the rest of its work won't need to be repeated. Documentation is the only way a company can talk to itself, and to its future.
