8 . 2 Configuration Management

"Command is getting people to go the way you want them to go enthusiatically." -General William Westmoreland

In engineering domains, a configuration is a particular arrangement of parts that reflect a realworld instance of a product. For example, one configuration is the particular choice of options and colors for a car. Version control, revision control, and change control are all names for activities closely related to configuration management. All these terms point to slightly different viewpoints of the way information is controlled, as well as changes over time. Configuration Management is a tool to manage a process for the creation of productsin this case, electronic documents.

The configured items that must be managed change over time. A configuration management system helps manage this change. Changes take place as a part is redesigned or a technical manual is revised for a new edition.

As projects grow more complex, formal configuration management will become necessary. Let's examine some of the basic functions that must be accomplished in creating a technical document. We will then look at how documents are managed during creation and what types of software can help coordinate and manage the process.

It is vital not to delude yourself into thinking that a configuration management system is going to solve your management problems. The system is only one portion of an overall solution. A clear set of organizational procedures and a clear understanding of exactly what needs to be configured are far more important parts of a managerial solution.

8 . 2 . 1 Configuration Items

The first thing to do when planning a configuration management system is to determine exactly what is to be configured. List these socalled configuration items and tailor them to your project. If you don't make this list, the various steps in the document development process will be a waste of time. The configuration items will be associated with products in the development processmaster copy, working copy, and so on. (3)

Configuration management becomes complicated when the individuals involved work with different systems. Authors in different organizations will often be working with different document processing systems. When their work must be integrated into a final report or other product, the complexities can become tremendous. Careful planning that identifies the configuration items, can prevent this problem. If you know ahead of time that two different types of graphics must be integrated, you can plan reasonable methods to integrate the two in the final document.

In addition, make sure that the original graphics and diagrams are appropriately saved in the configuration management system for future modifications. Be sure to capture the original editable versions of illustrations, tables, and graphics. It is easy to lose the original editable versions of graphics and diagrams, especially when one organization produces the graphics and another integrates them into the final product.

8 . 2 . 2 Roles and Functions

During the creation, production, and publication of a document, one person may take on many roles. In larger organizations, separate individuals may perform these roles. In any case, it is important to delineate who is responsible for what and when. It is useful to clearly understand these roles and how a "configuration management system" can and cannot solve certain problems. Each person has a specific role.

The author(s) create the document content and collaborates with others.

The editor changes stylistic and grammatical aspects of the document, but not the content.

The manager approves the document, often making editorial changes.

The producer merges illustrations and text (cut and paste) to produce cameraready output or electronic merging, assembly, and printing.

At each stage in the development of a document, a person performing a particular role must be in control of the current version of the document. When one person performs most of the roles, life is simple. However, in larger organizations and with complex documents, it is important to be clear about who owns a document and what precisely is the current document.

A configuration management system should help you manage and use the concepts of document ownership, signature authority, and security. In addition, the system should allow the grouping of files into a unit (often, a release of some sort) assigned a name or status such as DRAFT or RELEASE 7.

The configuration management system itself is primarily a management tool. It helps manage the complexity and coordination of many people working with shared information.

Now that we have identified the items to configure and understand the flow of these items through the organization, let's examine some software issues in configuration management.

8 . 2 . 3 Configuration Software

A wide variety of configuration management software systems are available. Similarly, a wide variety of document processing systems are available. Systems that integrate the two are not nearly as common. The ones that do exist are expensive, high-end "solutions."(4)

The range of configuration management systems is analogous to the range of electronic publishing systems. Publishing systems run the spectrum from batchlanguageoriented to WYSIWYG. Similarly, configuration management systems run the spectrum from suites of utilities to complete systems. Suites of utilities are functional. Some examples are those using the UNIX configuration control utilities Revision Control System (RCS) or Source Code Control System (SCCS), intended for source code control. These systems will require more of your technical staff's time to tailor them for document processing.

Databases can be used to add configuration management functionality to your document processing system. Information about what task is being performed and who is in control of the documents, along with status information, can be used to monitor the progress of the document's production. A database can add the additional functionality missing from a document processing system for configuration purposes. Security, shared access, and traceability are some of the capabilities that you can add by integrating a database with your publishing practices.

The integration of a database with the publishing system does not have to be a technical challenge. A perfectly reasonable solution is to assign a secretary or other staff member the responsibility of updating information in the database. You must also establish proper management practices to ensure that information about the changing document status is passed along promptly. Clear, reasonable organizational practices are much more important than the features of any particular configuration management system.

Let's turn our attention to those aspects of the document processing system that can be used to help the configuration management process. Invariably, publishing systems have a variety of features that can be used for configuration management, even if they were not intended for such use.

TYPOGRAPHIC AIDS

All electronic publishing systems allow a variety of typographic controls. Strikeouts, underline, overline, outlines, shadows, font changes, and change bars can all indicate visually the changes to a document. On-line reviews can use color as effective feedback. Before you select a particular convention, be sure that all members of the work group can use the particular visual cue. It is useful to establish a few guidelines and perhaps a key to identify the sources of the comments and the markup. Keep in mind that the purpose of a visual markup system is to allow traceability on the printed page.

Decide on what you want to indicate with the visual changes. Two possibilities are (1) to indicate who is making a commentary on the document and (2) to indicate a change in the document's content on a version by version basis. When too many fonts and strikeouts are used, the page quickly becomes unreadable. The following figure is functional but ugly. A mechanism for rebaselining and cleaning up the document should be part of the configuration process.

The more capabilities a document processing system has, the more possibilities there are for various types of visual indications. Don't take this too far, however. A document with half a dozen types of markup will probably be unreadable. The purpose of a visual indication of change is to give the reader an easy way to review the changes.

The field of on-line review and commentary is also gaining momentum. Products such as Lotus Notes and Adobe's Acrobat let groups mark up documents for review. The Computer Aided Logistics Support (CALS) program industry support group and the Institute of Electrical and Electronics Engineers (IEEE) have committees looking into electronic review of standards and specifications.

One interesting line of research in the area of on-line commentary and annotations has drawn inspiration from 15thcentury glossed bibles. The visual principles used in these works have provided fertile ground for research in hypertext and computersupported cooperative work.(5) Just as monks over the centuries made comments upon biblical passages, your boss can make comments on your work.

Groupware, the coordinated work of many individuals, has been heralded as the next computer revolution. (See Section 8 . 3 Groupware in this chapter for more information on Groupware.)

Research systems such as PREP (see previous illustration) and commercial products such as Rapport, Lotus Notes, BBN's Slate, and Instant Update are pointing the way into this largely uncharted territory. (Please see section Groupware in the appendix Resources.)

PAGE NUMBERING

Another low-tech configuration management device is the page number. If you produce a large set of documents that change periodically, you certainly don't want to republish everything just because of a change in page numbers. Two common techniques to avoid this problem are to use chapter-page numbering and point pages.

Point pages are simply inserted pages. For example, page 23.1 might be a new page inserted between pages 23 and 24. This technique does not require any reprinting of pages, and the reader may simply insert the page where it belongs. Once a year or so, the point pages are consolidated into "real" pages, and the document is republished.

Chapter-page numbering sequentially numbers all pages within one chapter. For example, page 4-23 refers to page 23 of chapter 4. This numbering scheme can also be used for figures and tables. New pages simply force the republication of individual chapters (or sections), rather than the entire document.

USERDEFINED ATTRIBUTES

Some electronic publishing systems allow the user to define an attribute and associate that attribute with portions of text. A good example of this is a capability called conditional text in the FrameMaker publishing system.

Conditional text can be used to maintain different configurations of a document. For example, a TOP SECRET document can be maintained as both secret and public versions by marking all the secret portions with a tag secret. The secret sections can be hidden and printed out only when required. A single document is maintained that contains both versions.

The userdefined attributes can associate comments with specific individuals. Thus the attribute LarryComments can be used to identify Larry's comments. Depending on the system's capabilities, you may be able to print or view only the portions of the text associated with a particular attribute. This kind of usage leads naturally to groupware types of applications.

8 . 2 . 4 ISO 9000

One important set of international standards for quality assurance and management is called ISO 9000. As part of the ISO 9000 suite, document management is required.(6) It includes:


Document management is critical to the successful completion of ISO 9000 certification. "Your organization shall control all your quality systems documents to assure availability of documented information to those who require it," states ISO Standard 9001.

The ISO 9000 quality assurance system includes 20 system elements documented in a pyramid of policies, procedures, and work instructions. Notice that many of these elements place requirements on a document management system. From the QBS Web site(7):

The 20 ISO 9000 Quality Assurance System Elements

An ISO 9000 compliant quality assurance system includes up to 20 system elements documented in a pyramid of inter-connected policies, procedures and work instructions. Of the three system models (ISO 9001, 9002, and ISO 9003), ISO 9001 requires all 20 system elements. The following summary is condensed from the International Standard document ISO 9001, second edition, reference number ISO 9001:1994(E).

1. Management responsibility:
to define, document, and implement a policy for quality.
2. Quality system:
to establish, document, and maintain a quality system which includes a
quality manual, system procedures, and quality planning.
3. Contract review:
to establish and maintain documented procedures for contract review.
4. Design control:
to establish and maintain documented procedures to control and verify the
design of the product to ensure conformance to specified requirements.
5. Document and data control:
to establish and maintain documented procedures to control all documents
and data (including hard copy and electronic media), including such documents as
standards and customer drawings.
6. Purchasing:
to establish and maintain documented procedures to ensure that purchased
product, associated documents, and data conform to requirements. Sub-contractors
are to be evaluated and selected on their ability to meet subcontract
requirements and the type and extent of control exercised by the supplier over
sub-contractors is to be defined.
7. Control of customer-supplied product:
to establish and maintain documented procedures for the control of
verification, storage and maintenance of customer-supplied product provided for
incorporation into the supplies or for related activities.
8. Product identification and traceability:
where appropriate, to establish and maintain documented procedures for
identifying the product from receipt and during all stages of production,
delivery and installation.
9. Process control:
to identify and plan the production, installation and servicing processes which directly affect quality, and to ensure these processes are carried out under controlled conditions.
10. Inspection and testing:
to establish and maintain documented procedures for inspection and testing activities to in order to verify that the specified requirements for the product are met.
11. Control of inspection, measuring and test equipment:
to establish and maintain documented procedures to control, calibrate and maintain inspection, measuring and test equipment (including test software) used by the supplier to demonstrate the conformance of product to the specified requirements.
12. Inspection and test status:
the inspection and test status of product shall be identified and maintained throughout the production, installation and servicing of the product to ensure that only product that has passed the required inspections and tests (or released under an authorized concession) is dispatched, used or installed.
13. Control of non-conforming product:
to establish and maintain documented procedures to ensure that product that does not conform to specified requirements is prevented from un-intended use or installation.
14. Corrective and preventive action:
to establish and maintain documented procedures for implementing corrective action in the handling of customer complaints, product non-conformities, and the application of controls to ensure corrective action is taken and that it is effective. Preventive action procedures will detect, analyze, and eliminate potential causes of non-conformities.
15. Handling, storage, packaging, preservation and delivery:
to establish and maintain documented procedures to prevent damage or deterioration of product.
16. Control of quality records:
to establish and maintain documented procedures for identification, collection, indexing, access, filing, storage, maintenance and disposition of quality records. Quality records shall be maintained to demonstrate conformance to specified requirements and the effective operation of the quality system.
17. Internal quality audits:
to establish and maintain documented procedures for planning and implementing internal quality audits to verify whether quality activities and related results comply with planned arrangements and to determine the effectiveness of the quality system.
18. Training:
to establish and maintain documented procedures for identifying training needs and provide for the training of all personnel performing activities affecting quality. Appropriate records of training shall be maintained.
19. Servicing:
where servicing is a specified requirement, to establish and maintain documented procedures for performing, verifying and reporting that the servicing meets the specified requirements.
20. Statistical techniques:
the supplier identify the need for statistical techniques required for establishing, controlling and verifying process capability and product characteristics, and shall establish and maintain documented procedures to implement and control their application.
The ISO 9000 documentation pyramid

The 20 quality assurance elements, or fewer elements in the case of ISO 9002 and ISO 9003, are incorporated in an interconnected documentation pyramid. The documents are indexed so that changes at one level do not require changes at a higher level, but may require changes at a lower level.

ISO 9000 Documentation Pyramid

Level 1: the quality manual and quality system elements

At the top of the pyramid is the quality assurance manual, which contains the corporate policy and statement on quality. Also included are brief statements describing how each of the applicable system elements are implemented in accordance with the company quality policy. The primary function of the 40 to 50 page quality manual is to succinctly define the company's quality assurance system to employees, management, and the ISO 9000 Registrar. It also acts as an excellent sales tool. The quality manual can be included with responses to proposals and other sales initiatives. It clearly confirms to prospective clients that they will be dealing with a quality organization that can provide goods or services in conformance with the clients' requirements.

Level 2: quality assurance procedures

The second level of the documentation pyramid contains quality assurance procedures that describe how, when, and where the quality system element activities are conducted, along with who is responsible for conducting them. Typically, each procedure is a few pages long.

Level 3: quality assurance work instructions

The third documentation level includes the detailed instructions for the performance of the work done by the company or organization. The work instructions include design specifications, drawings, service instructions, operating procedures, process sheets, etc.





[SECTION 8.3] [TABLE OF CONTENTS]

Skip to chapter[1][2][3][4][5][6][7][8][9]


© Prentice-Hall, Inc.
A Simon & Schuster Company
Upper Saddle River, New Jersey 07458
Legal Statement