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

A software engineering project uses a lot of documents. It uses requirements documents, use cases, design documents, test plans, user training material, lunch menus for team-building exercises, resumes if the project doesn’t go well, and much more. (I’ll describe these kinds of documentation in later chapters.) Even a relatively modest project could have hundreds or even thousands of pages of documentation.

To make matters more confusing, many of those are “living” documents that evolve over time. In some projects, the requirements are allowed to change as the project progresses. As developers get a better sense for which tasks will be hard and which will be easy, the customers may want to revise the requirements to include new, simple features and eliminate old, complicated features.

As the project progresses, the customers will also get a better understanding of what the system will eventually do and they may want to make changes. They may see some partially implemented feature and decide that it isn’t that useful. They may even come up with new features that they just plain forgot about at the beginning of the project. (“I know we didn’t explicitly say you need a way to log into the system, but I’m quite sure that’s going to be necessary at some point.”)

CHANGE CONTROL

If you let everyone make changes to the requirements, how can you meet them? Just when you satisfy one requirement, someone can change it, so you’re not done after all. (Imagine running after the bus in the rain while the driver cackles evilly and checks the side mirror to make sure he’s going just a little faster than you’re running.) Eventually, the requirements need to settle down so that you can achieve them.

Allowing everyone to change the requirements can also result in muddled, conflicting, and confusing goals and designs. This is more or less how laws and government spending bills are written, so it shouldn’t be a surprise that the results aren’t always perfect. (“Yes, you can have a $3,000 study to decide whether people should carry umbrellas in the rain if I can have my $103,000 to study the effects of tequila and gin on sunfish.” Someone really should spend a few dollars to study whether that kind of budget process is efficient.)

To keep changes from proliferating wildly and becoming hopelessly convoluted, many projects (particularly large ones) create a change control board that reviews and approves (or rejects) change requests. The board should include people who represent the customers (“We really need to log in telepathically from home”) and the development team (“The best we can do is let you log in on your cell phone”).

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.