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 lets you perform all sorts of other manipulations that are tricky inside an e-mail system. For example, you could write a program to search the files for messages from the user Terry that include the words “sick” and “Friday.” I’ve even had project managers who printed out every e-mail; although, that seems a bit excessive. Usually just having the e-mails saved in a project account is good enough.
Sometimes, it’s hard for team members to easily find project-related e-mails in the daily spamalanche of offers for cheap Canadian prescriptions, low interest rates guaranteed by the “U.S. National Bank,” letters from your long lost Nigerian uncle, and evacuation notices from your Building Services department.
To make finding project e-mails easier, you can prefix their subjects with an identifier. The following text might show the subject line for an e-mail about the CLASP project.
Of course, if you receive an e-mail with this subject, you should suspect it’s a hoax because all tasks have never been ahead of schedule in the entire history of software engineering. I think the day the term “software engineering” was coined, its definition was already a week overdue.
You can further refine the subject identifier by adding classes of messages. For example, [CLASP.Design] might indicate a message about design for the CLASP project. You can invent any message classes that you think would be useful. Following is a list of a few that may come in handy.
● Admin— Administration
● Rqts— Requirements
● HLDesign— High-level design
● LLDesign— Low-level design
● Dvt— Development
● Test— Testing
● Deploy— Deployment
● Doc— Documentation
●
