Читать книгу Beginning Software Engineering - Stephens Rod - Страница 32

Documentation is produced throughout a project’s lifespan, starting with early discussions of the project’s requirements, extending through design and programming, continuing into training materials, and lasting even beyond the project’s release in the form of comments, bug reports, and change requests. To get the most out of your documentation, you need to set up a document tracking system before you start the project. Then you can effectively use the project documents to determine what you need to do and how you should do it. You can also figure out what was decided in the past so that you don’t need to constantly rehash old decisions.

Document control is one of the first tools you should set up when you’re considering a new project. You can use it to archive ideas before you know what the project will be about or whether there will even be a project. Once you know the project will happen, you should start tracking the project with project management tools. The next chapter describes project management in general and some of the tools you can use to help keep a project moving in the right direction.

EXERCISES

1. List seven features that a document management system should provide.

2. Microsoft Word provides a simple change tracking tool. It’s not a full-featured document management system, but it’s good enough for small projects. For this exercise, follow these steps:

a. Create a short document in Word and save it.

b. Turn on change tracking. (In recent versions of Word, go to the Review tab’s Tracking group and click Track Changes.)

c. Modify the document and save it with a new name. (You should see the changes flagged in the document. If you don’t, go to the Review tab’s Tracking group and use the drop-down to select Final: Show Markup.)

d. On the Review tab’s Tracking group, click the Reviewing Pane button to display the reviewing pane. You should see your changes there.

e. In the Review tab’s Tracking group, open the Track Changes drop-down and select Change User Name. Change your user name and initials.

f. Make another change, save the file again, and see how Word indicates the changes.

3. Microsoft Word also provides a document comparison tool. If you followed the instructions in Exercise 2 carefully, you should have two versions of your sample document. In the Review tab’s Compare group, open the Compare drop-down and select Compare. (I guess Microsoft couldn’t think of synonyms for “compare.”) Select the two versions of the file and compare them. How similar is the result to the changes shown by change tracking? Why would you use this tool instead of change tracking?

4. Like Microsoft Word, Google Docs provides some simple change tracking tools. Go to http://www.google.com/docs/about/ to learn more and to sign up. Then create a document, save it, close it, reopen it, and make changes to it as you did in Exercise 2.

To view changes, open the File menu and select See revision history. Click the See more detailed revisions button to see your changes.

5. What does JBGE stand for and what does it mean?

▶ WHAT YOU LEARNED IN THIS CHAPTER

● Documentation is important at every step of the development process.

● Good documentation keeps team members on track, provides a clear direction for work, and prevents arguments over issues that were previously settled.

● Document management systems enable you to:

● Share documents with other team members.

● Fetch a document’s most recent version.

● Fetch an earlier version of a document.

● Search documents for keywords.

● Show changes made to a document.

● Compare two documents to show their differences.

● Edit a document while preventing someone else from editing the document at the same time.

● A simple way to store project history is to create an e-mail account named after the project and then send copies of all project correspondence to that account.

● You can use e-mail subject tags such as [CLASP.Rqts] to make finding different types of project e-mails easy.

● Types of documentation may include:

● Requirements

● Project e-mails and memos

● Meeting notes

● Phone call notes

● Use cases

● High-level design documents

● Low-level design documents

● Test plans

● Code documentation

● Code comments

● Extractable code comments

● User manuals

● Quick start guides

● Cheat sheets

● User interface maps

● Training materials

● Meta-training materials

● Marketing materials

● JBGE (Just Barely Good Enough) states that you should provide only the absolute minimum number of comments necessary to understand the code.