15.2 Document Handling

In a product's lifetime, many documents are created at different times and in different contexts. For instance, plans are created in connection with project management, and specification documents are created in connection with analysis and design. However, when talking about configuration management, documents are not generally the main consideration. The subject of this section is document handling in general. This means that the principles hold no matter when in the life of a product the documents are created and placed under configuration management.

Configuration Items or Deliveries

A document can be a single configuration item, but it can also be a delivery consisting of a number of components that are individually under configuration management. Such components may be general text, specific components (requirements, test cases, single chapters, sections), or drawings and diagrams. Figure 15-1 shows a document in the form of a delivery with components under configuration management.

Figure 15-1. Document Delivery

The smaller the units with which one chooses to work, the more precisely one can refer to the items and manage them, and the more precisely one can carry out tracing between them. On the other hand, with increasing granularity the amount of configuration items and metadata will increase, as will the amount of work.

Identification

Documents under configuration management must be identified. Because configuration items may appear on several levels in connection with documents, conventions must be defined for unique identification of these levels, which may be whole documents or components (requirements, drawings, and so on). Identification for these levels is described in detail below, as are the other aspects of identification.

Unique Identification of Documents

The unique identification of whole documents may be built up this way: PPPP_NNN.TTT n.n. Each of these elements has the function described in Table 15-3. The unique identification should be used in the file name for the document concerned and/or in the storage structure, according to conventions. It's up to each individual company to define details for each element, such as a list of permitted document types and rules for use of version and release designations.

Table 15-3. Unique Identification for Documents

Element	Function
PPPP_	Project or product to which the configuration item belongs
NNN	Document type, e.g.:
	NNN	Means
	URS	User requirement specification
	VVP	Verification and validation plan
	OP	Operation plan
.TTT	Reference to the production tool expressed by "." followed by a reference, e.g., "doc" for documents in Word
n	Version designation expressed by a running number
.n	Release designation expressed by "." followed by a running number or a letter. A convention may be used saying, for example, that as long as a document is in the form of a draft, letters are used in the release designation, while numbers are used when the document has been approved. In this way, a document may have these designations of version and release consecutively: 1.A, 1.B, 1.0, 1.1, 2.A, 2.0, 2.1, and so on.

Unique Identification of Components

The affiliation of components must form part of the unique identification. This affiliation may be implied in the physical placing of the componenta requirement written directly in a requirement specification document. The affiliation may also form part of the component identification, by including identification for the document of which the component forms a part. This may be the case if a component belongs only to one document and is stored in a database, for example. Where a component belongs to several documents (or other types of deliveries), the delivery must carry the relation "consists of," as described under metadata.

The unique identification of components themselves may be built up this way: BBBB h.h.h (nn) b.b. Table 15-4 describes the function of each element. Each company must define details for the single elements, such as in a list of permitted types of components and rules for unique numbering.

Table 15-4. Unique Identification of Subitems

Element	Function
BBBB	The component type: requirement or the like. This element is not often included, as the component type is normally implied in the context.
h.h.h	Number of paragraph or drawing or the like, specifying where the component is to be found in the document.
(nn)	The component's unique number within the context, to be used for tracing. The paragraph number (h.h.h) and this unique number (nn) must be independent of each other, for flexibility in the item's location and integrity in tracing. This makes it possible to move a component to another place in the document without having to change trace information.
b.b	Version and release designation for the component. This may follow the designation of version and release for the document, so a component may have the same or a preceding designation relative to the document, but this need not be the case. Components can have a life cycle quite independent of the one that holds for the document.

Authorization

Authorization for documents must be defined: whom each document is produced by, under the responsibility of, and approved by. Documents are often produced by several people who are experts within their own fields. Authorization information for document configuration items will often be stated in the document itself, on the front sheet or on a special sheet reserved for this information. Space may be left for signatures and dates. Electronic signatures may also be used where documents are only electronic, but this seldom occurs.

Tracing

Often it will be necessary to carry out tracing for document configuration items in a tool that is not the same as the storage tool, such as a separate database. This requires considering how the identification of single items can be exchanged between the storage tool and the tracing tool.

Storage

Documents are often available in files that are not ASCII format, such as documents written in Word or drawings produced with various tools for design and drawing. It may be complicated to find a configuration management tool that can store such configuration items, as most tools can handle only ASCII files. In such cases, it's necessary to build the file structure to handle the configuration management one wishes to perform.

It may be practical to create independent directory branches for each version and restrict the rights on the structure and the individual files. A whole branch can be made "read-only" when the delivery associated with it is approved and placed under configuration management.

It may be a good idea, for registering metadata and consistent status reporting, to create proxy configuration items for documents in the tool used for storing other types of items. This creates a bit more work with registration but provides an easier overview and facilitates status reporting.

Change Control

Event registration and handling of changes should be performed the same way for documents as for other items. Maybe this sounds self-evident, but it's not general practice to carry out document event registration with the same degree of accuracy as for, say, source code. Nor is it general practice to handle event registrations for documents in the same tool as other event registrations.

Status Reporting

In defining status reports for documents it's important to realize that information may be spread over several media. Metadata may be found in the documents themselves, and the documents may be stored in other places and in other media than are other configuration items. For this reason, one must expect extra work gathering and coordinating information from several sources.