Let me write that down: the genius of documentation

By David Walker (Google profile)

The document sitting next to the programmer's keyboard could best be described as a ragged sheaf. Held together by one of those giant bulldog clips, it sported dog-eared corners, torn pages, sticky notes, and half-legible scribbles in pencil and three colors of pen. It looked about as new-economy as a 1983 street directory. And yet to me, its co-author, that 145 pages represented a small triumph of the site-building process. It documented what the site should do, and it had been repeatedly, thoroughly, exhaustively used.

For a third of a century, the software engineering profession has taken documentation seriously - especially the "requirements" documentation which sets out what software should do. Web site creators and creators of Web applications have been slow to catch up. It's only recently that the Web site business has acquired a definitive volume on project management, Ashley Friedlein's prosaically-titled "Web Project Management", that makes documentation central to the site-building process.

But central it is. When the players in a project take up the written statement of the project's needs, update it, read it, play with it, pick holes in it - if all this happens, then the project will more likely than not succeed. If such "requirements" documentation languishes, or doesn't exist, the project risks foundering.

Documentation is easily trivialised. Many people, especially in the Web-building industry, see it filling for software the role that Hansard plays for Parliament - an after-the-case record of what was done, a record that you might just conceivably refer to later on. A few more see it as primarily a user manual or help file; yet others see it as the stuff that managers write on the side to help them understand the stuff the programmers are building.

The heck with that. Requirements documents only truly succeed when they're in the action, getting folded, knocked about and torn. Why would that happen?

• Because documentation can tell you what you're doing, and what you're not doing. This is more useful than it sounds, because software is Real Damn Complex, and building it takes time. You'll decide what the project does, but unless you document it, over time you'll remember different pieces of it with different levels of clarity, forgetting or adding in different features and solutions. Document, and you can give the entire enterprise clarity.
• Because documentation can tell everyone else what they're supposed to be doing too, which cuts down the size of the communication task. Minimising the communication task matters, because software is - at the risk of repetition - Real Damn Complex.
• Because documentation can forces consensus between interested parties. Technical experts, outside customers, marketers, the chief executive, whoever else has a stake in the project - the production of a clear project requirements document plays a key role in forcing them all to agree on what will be done. Suddenly your documentation is a conflict-killer: when Ms X asks later why your software has a Glerrt Diagram generator, you can quietly point her to the six pages headed "Glerrt Diagrams" in the requirements document she signed off on.

Clarity, communication and consensus are powerful things. And brought together, they can create a fourth desirable C - shared commitment to the project.

But there's one more important, overarching reason to create documentation for a Web project. It forces you and your team to decide what you want to do. It forces you to design. It forces you to strip away ambiguity and fuzziness and indecision, to decide just exactly what needs to be done. In short, it forces you to think.

Before that 145 pages got into the hands of programmers, I and my co-author, Lisa Liong, wrestled with it for weeks, all the while talking with members of the wider project team. We liked to pretend at the time that we controlled the documentation. In truth, it controlled us, its every inconsistency a rebuke to our thought processes, its every omission a snide laugh at our inability to create a coherent system. We had to consider and reconsider scores of small tasks the system would perform. How exactly would this calculation work? Where exactly would this page lead? What exactly would that error message say? Getting it right made our brains hurt, the way hard running makes your gut hurt.

That's why you document: because these questions need answers, and coders shouldn't have to invent third-best answers in the middle of writing some complex piece of application logic. Document well, and the people who code and build the pages of your site can get on with their work with the least possible fuss. And in the process, you hope, turn your documentation into a ragged sheaf of well-used pages.