- Guidance over Prescription
- Checklists and Signatures
- Real Design Issues: Diversification and Convergence
- Documentation and Common Knowledge
- Avoiding Evolutionary Complexity
- Post It!
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
Documentation and Common Knowledge
Documentation is one of the great four-letter words in the software industry, and often for good reason.
Most of us have at some point gone through a laborious exercise to create a document, only to see it whither, forgotten on the shelf. On the maintenance side, I’ve tried to add to an application by reviewing the design documentation, only to find that I had to review the source code to see what was really done. I’ve been involved in a project where the spec was created after the fact, as it was a deliverable item. I’ve also been through several projects where the requirements analysis phase involved far too little analysis and far too much paper.
What’s wrong with this picture?
When I hear that dreaded D word, I prefer to translate it to "shared understanding," as that is the essence of why we would choose to document information in the first place. As with any task on a software project, we should be clear that there is an anticipated benefit for the effort of putting a document together. Instead of viewing documents as the product of an intellectual activity, documents should be viewed as the persistence mechanism for the information generated from that activity. If it is worth retaining, it needs to be captured and shared.
Instead of "we have a specification, so we’re done with requirements analysis," it becomes "we have analyzed the user’s needs, and our findings are captured here."
So, how do we do this? To determine whether it is worth retaining at all, there are several drivers to consider, such as the expected lifetime and volatility of the information, criticality of the information to the project, how the information is gathered or obtained in the first place, and who the recipients of that information are.
After we’ve determined that a piece of information is important to retain and share, a wide variety of documentation options are available: e-mail, paper trails, discussion threads, wikis and intranets, traditional documents, presentation decks, flipcharts and whiteboards, index cards, databases, and blogs. Even word of mouth ("Bob’s got the donuts") can be a reasonable alternative for different types of information. Each alternative brings along different strengths and weaknesses.
One of the most effective approaches I’ve experienced was for the architecture for an air traffic control system, which evolved over a number of years in a large number of discrete elements, with a variety of authors and revisions for a large development team. There was no monolithic design document. We derived an evolving series of "ArchiNotes" that were each easily maintained and referred to as necessary.
Unfortunately, project teams often go for extremes. Documentation efforts can range from almost no documentation (the proverbial back of the envelope), which usually brings risks and rework to an unacceptable level, to ponderous documentation throughout, which can result in higher costs and maintainability issues.