Software projects require us to write documents. This is especially true on government and outsourced contracts, which often require developers to come up with requirements, design specifications, and/or maintenance documents. But software developers write software for a living, not documents. Developers are neither adept at, nor fond of, writing documents. This lack of skill and desire is a bad combination. Writing a decent document under these circumstances takes too much time. Developers need a way to jump-start the document they're writing, a way to talk and throw out information in any order. Then they need someone else to put the information on paper.
Here's my three-part technique for software project document writing. Start with a document standard such as the MIL-STD-498 for Software Development and Documentation (from the US Department of Defense) or the IEEE's new 12207 standard. Both standards contain expanded outlines for documents called Data Item Descriptions (DIDs). The document standard serves two purposes: It acts as a checklist to remind people what should be in the document, and it organizes the document by showing where to put what information.
Next, cut up the outline of the document and stick the pieces on a wall (or several walls). This permits the developers to see the layout of the entire document. Now, gather the developers -- as a group, not individually. Each person scribbles information on Post-Its and sticks the information on the wall. Grammar and spelling don't count. They also don't have to stick the information in the right section at first, as the Post-Its are easy to move around. What is important is to let the information pour out onto the wall.
The final piece is the recorder, who sits in the back of the group with a PC and enters the information poured out by the developers. When the developers are finished, the recorder touches up the finished document.
This simple technique works well for several reasons. First, everyone can see the entire document. This helps them think and contribute. Second, this method creates synergism. I know you've heard that word used and misused, but it does exist, and it does occur. When several people are thinking about the same problem together, they create better solutions than when working individually. Finally, the people who write software are not writing documents. They're scribbling and throwing information onto a wall. Someone else does the organizing, typing, and writing.
Dwayne Phillips works as a software and systems engineer for the US government. He recently wrote *The Software Project Manager's Handbook, Principles that Work at Work*, published by the IEEE Computer Society. He can be reached at d.phillips@computer.org.