Artistic Documentation

If programming is the meat of software development, then surely documentation must be the potatoes. Somewhat bland by itself, it still makes the main course more palatable and easier to digest. Generally all development projects have documents that describe its objectives. Depending on the size and complexity of your project, you may also have documents related to its deployment, operations, maintenance, and technical details.

Unless you are your own boss development starts by holding meetings with your sponsors to ferret out their requirements. A couple days after the meeting concludes, put together a formal document for the project sponsor to sign (sometimes called a Statement of Work) that explicitly demarcates the minimal need that the participants all agreed to. The purpose of this Statement should be to facilitate communication rather than to confine and restrain. Requirements change over time, so this initial spec should be "alive" and flexible.

On a large project you will next want to create design specifications for the programming staff. There is a balance along the path of a large project in cresting enough documentation to "float" the design without asking for so much that you sink creativity or subvert the sense of ownership. The purpose of a design specification should be to give the programmers enough guidance to plan their processing strategy and to alert them to what business rules might change or end up expanding.

Inside the actual programs we also find documentation. This is more or less hidden from everyone except the developers; its purpose is to serve as a memory aid and location tool when a developer goes back to revisit his code. You should compel the programming staff to write a reasonable amount of documentation: generally, a couple of lines of in-line comments for every ten to twenty lines of programming.

In addition, on a project that you expect to be mission-critical you should have the team develop standalone technical documentation that describes how all the pieces implement the business rules, paying attention to dependencies, configurable parameters, and reuse. The technical documentation should be clear, thorough, and detailed enough to allow a new member of the team to at least get his bearings in developing new code enhancements.

Although sometimes it does just seem like a chore or a side dish, documentation can make a big difference in the long term cost of maintaining a software system. And hey, some people like potatoes. (Some people really, really like potatoes... these are the folks who become Technical Writers.)