Unit 7Umenting the Solution

Unit 7.Documenting the Solution

The software development process is not only the production of code in machine-readable format but also the production of all the documentation—an intrinsic component of every project. Software includes all kinds of documents, produced at different phases of the software life cycle: specifications and design documents, planning documents, legal and accounting documents, management documents, and all sorts of manuals. Throughout this course, we have emphasized the importance of documentation. In this unit, we review the different types of documentation produced during the software development process that we outlined in Unit 2. We also discuss a few in greater detail and reiterate the criticality of good documentation as an intrinsic part of the software process.

7.1 The Documentation Life Cycle
7.2 Documentation during Implementation
7.3 Final Documentation
7.4 Why Document?
7.5 Documentation Aids

Assessments

Exercise 8
Multiple-Choice Quiz 7

There is no specific chapter or section of your textbook devoted to documentation, although references to the importance of documentation are found throughout. So, in this unit, there will be little additional reading.

7.1 The Documentation Life Cycle

Readings:

Schach (5th Edition), section 2.2.2, 2.3.2, 2.4.2, 2.5.2, 2.6.2, 2.7.2.

If you look at any of the life-cycle models described in Unit 2. Software Life Cycle, you will notice that there is no separate documentation phase. Documentation is an ongoing activity throughout the software process. The following table shows the documents associated with each life-cycle phase.

Life-Cycle Phase / Document Types
Requirements Analysis / Requirements document or rapid prototype
Specification / Specification document
Design / Architectural design
Detailed design
Implementation / Inline and module documentation
Module testing document, test suites, test results
Integration / Integration testing document, test suites, test results
Final documentation for delivery
Maintenance / Updated requirements, specification, design, testing documents
Updated module documentation
Retirement / No documents created

During the pre-implementation phases, the formal documents associated with each phase are the products of that phase. In the requirements analysis phase, there may be an actual text document, or requirements may have been elicited via rapid prototyping. In the latter case, the final prototype is the requirements document. In the specifications phase, the documents include all the different types of specification artifacts discussed in Unit 3. Analysis and Specification: informal specifications, data flow diagrams, control flow diagrams and decision trees, the data dictionary, input-output specifications, and entity-relationship models. In the design phase, documents include the formal architectural and detailed design documents. They may also include more informal documents, such as records of discussions over specific design issues.

For both module and integration testing, documents encompass instructions for testing and test suites (although they will be different in the two phases). Other types of documentation the organization will want to keep are the results of testing: for example, the number and type of faults found. As discussed in Unit 6. Build and Test the Solution, these test statistics will help the developer estimate the quality of individual modules and the product as a whole, be on the lookout for errors in subsequent tests of the same product and future products, and estimate the necessary amount of testing time remaining.

During maintenance, no new documents are produced from scratch, but documents from practically every phase of the life cycle will be subject to revision.

Documentation during implementation and in preparation for delivery will be discussed in greater detail later in this course.

7.2Documentation during Implementation

Programmers are responsible for documenting the code they work on. Code documentation includes both inline comments and more top-level documentation describing the code in a module or class in general. Only maintenance programmers having to fix a specific fault or SQA group members doing a code inspection are expected to read the code line by line.

In most software products, the code is divided into modules containing one or more functions, procedures, or classes—and variables that store state for the module. The prologue is the set of comments at the top of the module that describes the purpose and contents of the module in general. The following is a list of the information that should appear in the module prologue:

The module name
A description of what the module does
The programmer�s name (or names, if more than one individual is responsible for the module)
The date the module was coded
The date the module was approved and by whom
The module arguments (If more than one function, procedure, or class is contained in a single module, the prologue should give the arguments and a brief description of functionality for each item.)
A list of variable names in alphabetical order and how they are used
Names of files accessed by the module, if any
Names of files changed by the module, if any
Module input/output, if any
Error-handling capabilities
The name of the file(s) containing test data (to be used for regression testing)
A list of modifications made, by whom, on what date, and approved by whom
Known faults of the module

7.3Final Documentation

Maintainer's Documentation
Installer/Administrator Documentation
User Training Materials
User Reference Manual
User Quick Reference

Before delivering the product to the client, the developer must also produce a set of documents that will enable the client to install, use, and possibly maintain the software. These documents are among those that must be checked during product testing for correctness and consistency—among themselves and with the software. We describe each one of these documents briefly below.

Maintainer�s Documentation

Maintenance of custom software is likely to be done by the developer�s organization, but in some cases, the client will take over maintenance either right away or later during the maintenance phase. Maintainer�s documentation may include specifications, design documents, testing documents, as well as general documentation about the modules of the product and their interaction.

Installer/Administrator Documentation

The client will need to know how to install and generally administer the software product. These documents include instructions on:

Installation of the software on one or more platforms, if applicable
Initialization procedures, if required
Integration of updates and patches during maintenance
Any other activities related to the software product that would be performed by the systems division of the organization rather than the end users

User Training Materials

Training materials guide first-time and novice end users through the functionality of a system in a simple way. One approach to developing training materials is to present different scenarios of use, and lead the user through each one, using a realistic example throughout the scenario. Another approach might be to give examples of uses and then present example problems (with solutions) for the user to practice. Training materials should cover all the major functionalities of the system, but they do not necessarily have to cover every single aspect of the system. They may contain pointers to the user�s reference manual for more complex or less common operations, or they may provide training for these operations in staged scenarios ordered by complexity.

User Reference Manual

A user reference manual contains a complete description of the functionality available in the product. Reference manuals contain lists of available APIs or interface operations, organized by topic or by the major functions performed by the system. The user reference manual should explain all relevant terminology and provide complete descriptions of all aspects of the system.

User Quick Reference

A user quick reference is a brief document or card that shows at a glance the functionality available in the system and how to access it. If the system is not very large or complex, the quick reference may be able to include brief descriptions of all the functionalities (commands) and expected arguments. In larger systems, it is probably only feasible to provide a list of the most common operations organized by topic—and a reference or link to more detailed information in the user reference manual.

7.4 Why Document?

The attitudes of organizations toward documentation can vary widely. Some organizations consider the software they produce to be self-documenting—that is, the product can be understood simply by reading the source code. Unfortunately, as we noted earlier, self-documenting code is rare indeed. Other organizations are far more documentation intensive. They meticulously create specifications and detailed design documents for the implementers. The testing process is carefully planned and its results logged. Requests for changes during the maintenance period have to be submitted in writing, justified, and formally approved. Once authorized, modifications are not incorporated into the product until the documentation has been updated and the changes approved. Organizations that devote the proper amount of attention to documentation will find that investment in this effort pays off.

In the waterfall model, it is stipulated that no phase is complete until the documentation and other artifacts of that phase have been completed and approved by the SQA. Even in other life-cycle models, it is important for several reasons that each phase be fully documented for the current version of the product before the next phase begins. First, if the documentation is postponed, the pressure to deliver a product on time may be such that the documentation is never completed. Second, the individuals who were responsible for earlier phases of the project may no longer be working on that project or even for the same organization. Third, a design will often be altered during implementation, and unless the design has been fully documented by the team, it will be difficult to carry out the modifications and to document the design after the changes. Fourth, poor documentation, no documentation at all, or, even worse, incorrect documentation is a nightmare for maintenance. Due to the very high rate of personnel turnover in the software industry, it is almost certain that the programmers who will be maintaining the product are not the same individuals who developed it.

For all the above reasons, the management of the developer�s organization should plan—from the beginning of the entire software project—for a thorough documentation process. Documentation should be updated continually to reflect the current version of the product. Documents pertaining to each life-cycle phase should be completed by the same people who participated in that phase. Finally, before delivery to the client, the documentation must undergo a final check to make sure that it is complete and consistent with the code.

It is likely to be up to the developer to remind the client that allocating proper resources to documentation is a priority for both sides. A badly documented product will require more money and more time to maintain. Poor documentation may also end up being a motivation for replacing the product rather than maintaining and enhancing it—a course of action that can be very disruptive to the client�s organization.

7.5Documentation Aids

Readings:

Schach (4th Edition), section 8.9.
Schach (5th Edition), section 9.9.
Schach (6th Edition), section 9.9.

Producing documentation can be a significant portion of an organization�s activities during software development. Studies of selected product development efforts have shown that an organization may produce from 28 to 66 pages of documentation per 1000 instructions (KDSI) for an internal or commercial product of around 50 KDSI. For operating system software, the number may go as high as 157 pages of documentation per 1000 KDSI. These studies considered various sorts of documents, including planning, control, financial, and technical documents—as well as comments in the code. Moreover, a survey of 63 development projects and 25 maintenance projects showed that for every 100 hours spent on activities related to code, 150 hours were spent on activities related to documentation and, in some cases, up to 200 hours.

Because documentation can consume so much of an organization�s resources, it is vital to make the process of developing and maintaining documentation as efficient as possible. CASE tools can help with organizing and keeping up to date of all kinds of documentation, such as plans, contracts, specifications, designs, source code, and management information. Not only do CASE tools reduce the drudgery associated with these tasks, they can also help in making documentation available online. Online documents are easier to search and to change. Furthermore, it is significantly more cost-effective to make document modifications in one location and make the most recent version available online to all interested parties than it is to keep redistributing corrected paper copies.

A different kind of aid to effective document production is documentation standards. Uniform coding standards assist maintenance programmers in understanding source code. Standardization is even more important for user manuals, because these have to be read by a variety of users, few of whom are computer experts. Uniformity in documentation also reduces misunderstandings between team members and aids the SQA group in performing their job. If documentation standards are consistently applied throughout an organization, new employees will need to be trained in applying the standards when first joining an organization, but they will not need retraining when they change departments within the organization.

Standards for all the documentation that is to be produced during software development must be established during the planning process and incorporated into the software project management plan (SPMP). Where standards already exist, they should be adopted (for example, the IEEE Standard for Software Test Documentation [ANSI/IEEE 829, 1983], or the IEEE Standard 1063 for Software User Documentation). Schach (4th Edition), figure 8.8 or Schach (5th Edition), figure 9.8 or Schach (6th Edition), figure 9.8 shows the framework for a SPMP. Existing standards should appear in section 1.4 of the SPMP (Reference Materials) and effort-specific standards in section 4.1 (Methods, Tools, and Techniques).

Take Assessment: Exercise 8

窗体顶端

Please answer the following question(s).
If the assessment includes multiple-choice questions, click the "Submit Answers" button when you have completed those questions.
1. / Go to bottom of question.

Project Documentation

Final code documentation: Is your final implementation consistent with your original detailed design, or were you motivated to make some changes? Review all of the detailed design documentation (javadoc comments) in your class files, and update where necessary. Generate a new version of the design documentation (HTML pages) using javadoc(

Final user documentation: Write a Word document that describes in detail the steps that should be followed to install and run your software. If there are any configuration files or global parameters that the user must set or modify to install the software for their particular installation, be sure to document them.

窗体底端