Writing Team Documentation

---

All of the documentation I’ve talked about so far has an audience outside your company; it’s all intended for users of your application. But that’s not the only potential audience for documentation. In particular, if you’re working with a development team or as part of a continuing development organization, there’s a need for internal documentation that will likely never leave the company. I’ve mentioned various internal documents along the way, such as the top five risks lists, project requirements, and specifications. I’d like to point out two other important documents specifically: the development log and the postmortem.

Development Log

When you’re working by yourself on an application, it’s usually pretty easy to remember what you’ve done already, what you still need to do, and what the next five steps in the process should be. However, when you add in a team of people, perhaps scattered around the globe, the problem of keeping track of development becomes much more complex. I’ve seen projects waste a lot of time because developers didn’t coordinate their actions, in some cases overwriting each other’s work time after time.

Many strategies are available to combat this problem. In some cases, a strong manager can impose such order on a team that the manager’s feel for the process controls everyone’s actions. In other teams, particularly long-lived ones that put out multiple versions of a product, one developer will end up being the team’s institutional memory. This is the person who, in any given meeting, can recall the discussions from three years back and remind people why a particular decision was made. (If your team depends on such a person, treat that individual well; his or her contribution is irreplaceable).

But particularly if your team is community based rather than hierarchical, it can be useful to replace these ad-hoc solutions with a written development log. Such a log need not (and should not) be a detailed description of every change made to the code; your source code control system should be able to supply that when you need it. Instead, it’s a place where team members can look up key facts about the project:

• What the overall architecture of the application is, and why that architecture was chosen over alternatives

• Who’s responsible for each part of the application or for each function on the team

• Where key pieces of the network are located: Which server handles source code control? Which one is the build machine?

• What tricky problems came up, and how they were solved

In the ideal world, the development log contains the information you need whenever a question comes up in a meeting and people can’t quite remember what happened. In the past, I’ve used Word documents and web pages for development logs, with all team members having the necessary permissions to edit the joint document when they have something to add. These days, I think I’d use wiki or weblog software for this purpose, since those tools have developed to allow easy joint editing of shared content. A SharePoint site would be another good alternative.

Postmortem

In contrast to the development log, the postmortem is typically written only after the application is finished and shipped. The purpose of a postmortem is to record the lessons that the team or the manager learned in the course of building the software (or the things that they wish they had known before they started). A typical postmortem might include these sections:

• Overall description of the project

• Who was involved on the team

• How the project’s scope and features changed from initial design to final ship

• A list of things that were done well during the project

• A list of things that could have been done better

• A list of the tools used, along with an evaluation of their quality

• A list of tools that team members wish they had had available

• A list of important project documents with their locations

• Recommendations for the next project: How can things be done better?

Postmortems are most useful when all team members have an opportunity to add to them, and when they’re encouraged to speak freely. You should never tie performance reviews to postmortems. Instead, provide a mechanism for anonymous contributions from team members who feel threatened by the process. In a healthy software organization, postmortems are an accepted part of software development, and one with a history of helping rather than hurting careers.

TECHNOLOGY TRAP: Experience in a Locked Cabinet

Douglas Adams wrote of a particularly critical piece of documentation being stored “at the bottom of a locked filing cabinet stuck in a disused lavatory with a sign on the door saying ‘Beware of the Leopard.’” This is not what you want to have happen to your team documentation. There’s little point to spending time creating a postmortem if no one is ever going to read it.

If you’re introducing postmortems to your organization, think about ways to make sure the lessons learned are shared by everyone who can benefit from them. Some things to consider:

• Establishing an e-mail alias to notify people when such documents exist

• Storing the documents in a specific folder on the network or on an intranet site

• Reminding managers to make reviewing past postmortems a part of planning any new project

Of course, if you’re a lone developer, this sort of process issue won’t apply to you. You’ll just have to remember to review your own postmortems. Reminding yourself of this in a postmortem report is a futile gesture!

---