Escape from Documentation


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.

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.