Even on small projects, it’s usually worthwhile to assign someone as the final arbiter. Often that person is either a high-ranking customer (such as the executive champion) or a high-ranking member of the development team (such as the project lead).
During development, it’s important to check the documentation to see what you’re supposed to be doing. You need to easily find the most recent version of the requirements to see what the application should do. Similarly, you need to find the most recent high-level and low-level designs to see if you’re following the plan correctly.
Sometimes, you’ll also need to find older versions of the documentation, to find out what changes were made, why they were made, and who made them.
FONT FIASCO
To understand the importance of historical documentation, suppose your application produces quarterly reports showing projected root beer demand. At some point the requirements were changed to require that the report be printed in landscape mode with a 16-point Arial font.
Now suppose you’re working on the report to add new columns that group customers by age, weight, ethnic background, car model, and hat size. That’s easy enough, but now the report won’t fit on the page. If you could bump the font size down to 14-point, everything would fit just fine, but the 16-point Arial requirement is killing you.
At this point, you should go back to the requirements documents and find out why the font requirement was added. If the requirement was added to make it easier to include reports in PowerPoint slides, you may be able to reduce the font size and your boss can live with slightly more crowded slides during his presentations to the VP of Strategic Soft Drink Engineering.
Another option might be to continue producing the original report for presentations and create a new expanded report that includes the new columns for research purposes.
It’s even possible that the original issue was that some developers were printing reports with the Comic Sans font. Management didn’t think that looked professional enough, so it made a font requirement. They never actually cared about the font size, just the typeface. In that case, you could probably ask to change the requirement again to let you use a smaller font, as long as you stick with Arial.
Unless you have a good document history, you may never know why and when the requirement was changed, so you won’t know whether it’s okay to change it again.
Meanwhile, as you’re changing the font requirement to allow 12-point Arial, one of your coworkers might be changing some other part of the same requirement document (perhaps requiring that all reports must be printed in renewable soy ink on 100 % post-consumer recycled paper). If you both open the document at the same time, whichever change is saved second will overwrite the other change, and the first change will be lost. (In programming terms, this is a “race condition” in which the second person wins.)
To prevent this type of conflict, you need a document control system that prevents two people from making changes to the same document at the same time.
To handle all these issues, you need a good document management system. Ideally, the system should support at least the following operations:
● People can share documents so that they can all view and edit them.
● Only one person can edit a document at a given time.
● You can fetch the most recent version of a document.
● You can fetch a specific version of a document by specifying either a date or version number.
● You can search documents for tags, keywords, and anything else in the documents.
● You can compare two versions of a document to see what changed, who changed it, and when the change occurred. (Ideally, you should also see notes indicating why a change was made; although, that’s a less common feature.)
Following are some other features that are less common but still useful:
● The ability to access documents over the Internet or on mobile devices.
● The ability for multiple people to collaborate on documents (so they can see each other making changes to a shared document).
● Integration into other tools such as Microsoft Office or project management software.
● Document branches so that you can split a document into two paths for future changes. (This is more useful with program code where you might need to create two parallel versions of the program. Even then it can lead to a lot of confusion.)
● User roles and restricted access lists.
● E-mail change notification.
● Workflow support and document routing.
Some document management systems don’t include all these features, and some of these aren’t necessary for smaller projects, but they can be nice to have.
The following sections describe some special features of different kinds of documentation that you should save.
HISTORICAL DOCUMENTS
After you’ve installed some sort of document management system, you may wonder what documents you should put in it. The answer is: everything. Every little tidbit and scrap of intelligence dealing with the project should be recorded for posterity. Every design decision, requirements change, and memo should be tucked away for later use.
If you don’t have all this information, it’s too easy for project meetings to devolve into finger-pointing sessions and blame-game tournaments. Let’s face it; people forget things. (I’m writing Chapter 2 and I’ve already forgotten what Chapter 1 was about.) Not every disagreement has the vehemence of a blood feud between vampires and werewolves, but some can grow that bad if you let them. If you have a good, searchable document database, you can simply find the memo where your customer said that all the monitors had to be pink, pick the specific shade, and move on to discuss more important matters.
Collecting every scrap of relevant information isn’t quite as big a chore as you might think. Most of the information is already available in an electronic form, so you just need to save it. Whenever someone sends an e-mail about the project, save it. Whenever someone makes a change request, save it. If someone creates a new document and doesn’t put it in the document repository, put it there yourself or at least e-mail it to yourself so that there’s a record.
The only types of project activity that aren’t usually easy to record electronically are meetings and phone calls. You can record meetings and phone calls if you want a record of everything (subject to local law), but on most projects you can just type up a quick summary and e-mail it to all the participants. Anyone who disagrees about what was covered in the meeting can send a follow-up e-mail that can also go into the historical documents.
It’s also well worth your effort to thrash through any disagreements as soon as possible, and sending out a meeting summary can help speed that process along. The biggest purpose of documentation is to ensure that everyone is headed in the same direction.
Memos, discussions about possible change requests, meeting notes, and lunch orders are all easy to distribute via e-mail. Storing those e-mails for historical purposes is also easy: Simply CC a selected e-mail address for every project e-mail. For example, you could create an e-mail address named after the project and copy every project message to that account.
Suppose you’re working on project CLASP (CLeverly Acronymed Software Project). Then you would create an e-mail account named CLASP and send copies of any project e-mail to that account.
TIP I’ve had project managers who extracted every project e-mail into text files and tucked them away in a folder for later use. That