Place Tab A in Slot B

When you're building a system, your primary goals are to ensure that the system works, that it meets its users' needs and that it provides value to your organization. You also want to create software that can be maintained and enhanced over time after it's been deployed.

These secondary goals are supported by sufficient system documentation—and that means written descriptions of the applications, not just comments in your source code. While design models, requirement specifications and user manuals potentially make the grade, management artifacts such as project schedules don't.

Here, I'll discuss the post-development write-ups that support systems in the production phase. What types of documents do you need to deliver and when do you know if they're sufficient? The answers may surprise you.

Guiding Principles
Let's start with some guiding principles—first, Extreme Programming (XP)'s
(www.extremeprogramming.org) tenet of traveling light. Your project team will be more agile, hence more effective, with minimal baggage. The fewer documents you create and maintain, the more time you'll have for development. However, you must remember the people who will operate, maintain and use your system. Individuals who weren't actively involved in development (and in a large organization, that can be a lot of people) will need a way to understand and work with your system effectively.

Summary documentation is one means to that end. Simplicity, another XP fundamental value, teaches that the best documentation is the simplest that gets the job done. Don't babble on for 50 pages when five will do. Don't create an intricate diagram when a sketch will suffice. Don't repeat information found elsewhere when a brief reference will do. Furthermore, rough-draft system documentation created during active development can help to streamline the entire development process. Of course, you have to keep progress and documentation in balance; remember that any in-development documentation must be updated to reflect midstream changes. This can increase your documentation burden and impede your development velocity.

Finally, "develop with a purpose"—a fundamental principle of the methodology I call Agile Modeling (formerly Extreme Modeling; go to www.extrememodeling.com). Document only to fulfill clear, important and immediate needs.

Who Needs What?
I don't believe that an application is truly delivered until it's in production and the required documentation rests in the appropriate hands. What system documentation should you include when your project is ready for production? You must identify your documentation's potential customers, determine what information they believe they need and then work with them to produce documents that address their actual requirements.

System documentation customers span varied personnel: the users themselves, the operations staff that will run the system, the support staff that help users work with the system and the maintenance professionals who will adjust the system over time. Ask them what they do, how they do it and how they want to work with the system documents. Then listen to their answers.

So, what types of documents will you need to produce? Your users may require a reference manual, a users guide, a support guide and even training materials. Different requirements demand different media: Electronic documents are OK for quick lookups and additional help, but users guides and extensive training material often require a paper format. I learned long ago to base my users guide and training materials on the use cases for the system—use cases describe how people work with the system, and so provide a firm foundation on which to base both of these documents.

Operations personnel are often concerned with a system's interaction with other systems, databases and files. This documentation should be easy to produce because you've already handled these types of questions throughout the development phase.

I've always found it useful to meet with my operations folks early in the project's life cycle. Because I wanted to discover their requirements as early as I can during any project, I extended the deployment workflow into the Inception phase of the enhanced life cycle for the Unified Process (www.ronin-intl.com/publications/unifiedprocess.htm).

Some operations departments will require an intricate deployment model ("Effective Software Deployment," Nov. 1999) that delineates each type of hardware node in the system, the software deployed to them, the middleware between them and any relationships they have with external systems (and vice versa). I've also worked with operations departments that wanted only release notes listing the various system components, their version numbers and their interdependencies. Most operations departments will also want documented backup procedures, the availability and reliability requirements for the system and the expected load profile of your system. And, of course, they need to know the system's contact personnel and how to reach them. It's clear that your operations department may require a wide range of documentation, so be prepared.

Your support department will probably request system training materials specific to their needs. This may be as simple as a page or two of notes for your development team to follow when training new employees, or as complex as manuals for both the instructor and trainees, a video tutorial or even a computer-based training system. For problem-solving reference, support staff will also want access to any documentation provided to your users. A troubleshooting guide, perhaps in the form of an online knowledge-base that support staff can update as they solve new problems, may also be required. Escalation procedures for handling difficult problems will also be necessary. Support departments often have these in place already and may need only minimal updates.

For maintenance professionals, the primary artifact is quality source code, and Andrew Hunt and David Thomas's book, The Pragmatic Programmer: From Journeyman to Master (Addison-Wesley 2000), provides excellent advice for writing such code. In addition to well-documented source code, your system's maintenance team will require an overview of the system and an indication of where to go for more detail. I like to write a "Good Things to Know" document during development. Typically short and to the point (usually fewer than 10 printed pages), it summarizes key information such as the system's mission, primary user contacts, development tools and technologies, and critical operating processes (both development and production). I also include references to important project artifacts such as the location of the source code (the project name in the source-code control system is often sufficient), the critical models pertaining to the system (if any), and other essential data.

Enough is Enough
When is a document sufficient? When it's as small and simple as possible, but still gets the job done. To pare a document to fighting trim, I'll ask my customers how they intend to use it and why they're using it that way. It's not enough to say, "We need a logical data model because our procedures say we do" or "We need a logical data model because we tell you so,"—they must explain why they need it. With a little persistence, patience and tact, you can effectively ease your project's documentation burden. Sometimes you can trim to the point where you don't need an artifact at all; at the least, you can usually condense the artifact itself—a brief list of bullet points might well replace a users manual written in full prose.

Negotiating an artifact down to its minimal qualities can be a straightforward process—when you are working with reasonable people. But sometimes, reason takes a back seat, and you'll be in for a bumpy ride. People can be threatened by new ideas, such as basing a physical data model on a class model instead of a logical data model or using pair programming techniques to write cleaner code. When negotiation comes to a halt, you must be willing to take another approach, such as moving the decision up the management chain. This requires exquisite finesse: Remember, there is no such thing as a politics-free software project.

The Customer is King
In your zeal for reducing documentation, keep in mind the teeter-totter of excess and insufficiency: Remember that the customer, not the writer, determines what's necessary. Years ago, I worked for a large Canadian financial institution that had the wise policy of requiring the artifact's customer—be it a maintenance developer to whom you were transitioning your code or a user for whom you were building the system—to accept that artifact. Individual artifacts were inspected by the customer, and if they weren't deemed up to par, the development team returned to the drawing board, sometimes working with customers to ensure a successful round two. This practice provided a fair and effective checks-and-balances system for both developer and customer.

To best determine whether a document passes muster, let a representative of its target customer base work with it. Does the document provide needed information, and is it accurate? Does the document offer more data than is necessary? A developer new to your team can check out the "Good Things to Know" document, user acceptance testing can provide a perfect venue to evaluate user documentation, and an operations engineer can try out the backup procedures.

Supporting artifacts, particularly documentation, are a vital element of modern systems. To move your system successfully into production, you need to create concise, thorough system documentation that meets the needs of its customers. This doesn't mean that you must create something whose size puts the Encyclopedia Britannica to shame—by working with, not against, your project stakeholders, you can often travel much lighter than you expected, and create documentation that is both succinct and sufficient.

Note: I'd like to extend thanks to Martin Fowler and Neil Pitman for providing input for this article.