Wednesday, March 7, 2001

Document or Die, 20 Years Later

Roger Mills, Past Chair

Programs, operating systems, and utilities will not be purchased if they can't be used. There is no excuse for "Programmerese"! There is no substitute for good English! "This sentence, no verb" tee shirt should be displayed in every program area. CD-ROMs are great for quick reference, but why do you think all of those books are written which explain how to use programs?

During the speech or at the end, there will be an opportunity for rebuttal.

Roger Mills has been an ACM national and chapter member since 1957, Chapter Chair twice (19 years apart), ACM Southern California Regional Representative, and Chair of the ACM Professional Code of Conduct when the first code was developed. He ran for ACM President in 1980, and was a national lecturer in early 80s.

He retired from TRW in 1989, and is presently a credentialed secondary school substitute math teacher for the Palos Verdes Peninsula School District, and a volunteer instructor at Palos Verdes on the Net. He has been in the computer field since January 1951.

LA ACM Chapter March Meeting

Held Wednesday, March 7, 2001

"Document or Die" 

Presented by Roger Mills an ACM and LA Chapter member since 1957. He retired from TRW in 1989.

Roger gave us a fast overview of the necessity for good documentation practices in the development of good software. Requirement, design, interfaces, and code are all documented in printed format. This should include well-annotated code. This starts out with doing good software requirements analysis to insure that good designs are possible, that the tested requirements will validly demonstrate system capabilities, that users are brought into the loop and so that management personnel can really be in control of the development process. The preliminary users manual should be developed at an early stage. One change during recent years has been that the users manual will be on a CD-ROM. Hal Hart commented from the audience that the documentation is also going on line for easier access.

It is necessary to develop a software documentation plan that identifies document types, schedules all documentation, defines documentation reviews and audits, production and distribution of documents, and estimates documentation costs. Roger went through a list of things needed to produce good documentation and emphasized that the responsibility for each part must be definitely assigned or it either won't be generated or will be of doubtful quality. It is very important to set the document delivery date, because all other dates are backed up from the delivery date. The necessity for security reviews and for any time needed for deliveries must be included in the schedule. Draft publication dates must be set early enough to allow for both review and to incorporate changes prior to producing the final document. Reviewers should be selected because they have the capabilities required to do a good technical review, not just because someone is available. Copies should be available for all of the reviewers.

Documentation audits should be accomplished during the phase of the development that is audited. The audit is done not just to verify that the document exists, but to insure that the document describes those things that either have been done or are in the process of being done according to the plan. The services of a good editor are very important, as programmers tend to write in jargon, which is sometimes difficult to interpret. The author must review the edited version before publication to ensure that any of the editor's changes intended to improve readability have not changed the intended meaning. Roger pointed out that production costs of the physical document is usually straightforward, but the cost of the programmer's time to generate the material is usually ignored or underestimated.

There are three primary documentation types; Management Reports, Standard Forms, and Technical Documentation. Management Reports include monthly reports, critical path method charts, PERT networks for integrating activities and their dependencies and technical review meeting minutes. Standard forms provide consistency within the project for reporting problems, changes and fixes.

The emphasis of Roger's presentation was on technical documentation which includes Software Requirements, the Software Development Specification, the Software Product Specification, Test Plans and Procedures, the Users Manual, and Test Reports. Requirements analysis is especially important. It should create a description of product performance as determined from the system functional requirements the software will be required to meet. Sometimes the customer will also specify the programming language to be used and a general methodology to be followed in the design and implementation. Requirements analysis should provide well reasoned substantiation, not provide conflicting requirements and should be complete. Each requirement should be capable of being identified with at least one system requirement. The requirements should not specify the design approach, should meet the coordinated goals of the buyer, seller, and user. Too often the buyer and the seller agree on requirements and leave out the user who is frequently disappointed with the resulting software that he must live with. Every requirement must be testable. If it can't be tested then it really isn't a requirement, but just a wish. Each requirement must be validated to sell off the software.

Roger emphasized the importance of the Unit Development Folder (UDF). A unit is a well-defined set of software that performs a function and is the responsibility of a single programmer. A UDF is created and maintained by that programmer for each of his units. The UDF provides information for generating the preliminary design package, the detailed design package, the interface control document, and the test plans and reports. It provides a common collection point for all of the necessary information to conduct a review at any milestone along the development cycle. It provides the information necessary for middle management to have visibility on the status of the software and to control its development. The programmer establishes development milestone dates that he must meet in order to meet his unit delivery date, with the concurrence of his Work Package Manager. Roger described the Preliminary Software Development Specification that contains a functional description of all of the software that must be produced. This is accomplished before the Preliminary Design Review (PDR) which should be the point where there is final agreement on the requirements. Where required, the System Engineer should establish storage and timing budgets. A Preliminary User's Manual should be provided and should be the foundation for extensive CD-ROM help files. Each unit should be well defined and a set of test plans generated during preliminary design. The Critical Design Review (CDR) should defined down to the "code to" level in sufficient detail to design each routine in the element. The Interface Control Document (ICD) is finalized at CDR and placed under internal baseline control. Any changes made by a developer must be known and agreed upon by the other developers before changes are implemented.

Roger Mills was called upon on short notice to update his talk that was developed 20 years ago and present it to the LA Chapter meeting audience. His points are still quite valid. Comments from the audience were that the main change that has occurred lately is that more and more documentation is being made available online so that people can review it from remote locations and discussions can be also be done online. There was general agreement that face-to-face meetings were still valuable and necessary.

This was seventh meeting of the LA Chapter year. 

Mike Walsh, LA ACM Membership Chair