August/September 2003

Volume 44, Number 1

Document management for dummies

by David Dick and Kathy Bine

The typical project consists of a seemingly overwhelming amount of documentation: proposals, plans, meeting minutes, customer requirements, functional requirements, use cases, test plans, design specifications, an overall design document (including high level design and detailed design), user guides, system administrator guides, installation guides, and training manuals. It may also include press releases, marketing brochures, service descriptions, and release letters. The documents are updated several times throughout the project's life cycle. In the absence of a documentation management policy, there is no consistent and proven approach to ensure quality.

Controlling documents does not mean creating bureaucracy. It means regulating the development, approval, issue, change, distribution, maintenance, use, storage, security, and disposal of documents.

Good documentation management ensures the following:

• Documents fulfill a useful purpose
• Resources are not wasted on distribution of non-essential information
• Only valid information is published
• Information is kept up-to-date
• Information is in a form that can be used by relevant people
• Classified information is restricted to the people who have a need to use it
• Information is retained that could help investigate a problem, improve opportunities or deflect potential litigation

So, how to get your document management under control? Begin by defining your strategy. Create a process that fits your strategy and put it to use. The following sections describe some of the most important points to consider.

Define a documentation management strategy

A documentation management strategy should be supported by a procedure that defines multiple steps, including:

• Planning new documents: funding, authorization, establishing need, and so forth
• Preparation of documents: who prepares them, how they are drafted
• Standards for the format and content of documents, tests, forms, and diagrams
• Documentation identification conventions
• Issue notation, draft issues, post approval issues
• Dating conventions, date of issue, date of approval, date of distribution
• Document review: who reviews them and what evidence is retained
• Document approval: who approves them and how approval is donated
• Document proving prior use
• Printing and publication: who does it and who checks it
• Distribution of documents: who decides, who does it, who checks it
• Use of documents, limitations, unauthorized copying, and marking
• Requests for revision: who approves the requests, who implements the changes
• Denoting changes: revision marks, reissues, sidelining, and underlining
• Amending copies of issued documents, amendment instructions, and amendment status
• Indexing documents, keeping them current, and periodic review
• Document filing, masters, copies, and drafts
• Document security, unauthorized changes, copying, disposal, computer viruses, fire, and theft

Many of these processes can be automated by a documentation management tool. Only tasks performed by staff need to be defined in your procedure.

Create a documentation review board

The documentation review board consists of the following members:

• Reviewers are subject matter experts who judge whether the information is accurate, reflects their needs, and satisfies the intended purpose
• The Author is the person(s) assigned to create the document
• The Approver is the person(s) who approves publication of the document

To avoid extensive lists of reviewers, the author and approver may select a representative from each area who is responsible for consolidating their team's comments. The representative distributes the document within their team, but remains personally responsible for filtering and consolidating feedback before contacting the author.

Conducting a documentation review

Documentation review ensures that the appropriate people approve information and allows authors to address any issues prior to publication.

Typically, the author sends the document and a document review form to the review board. Distribute the document (via the document management server, or DMS) to the review board and provide a standard comment sheet for comments and suggestions as to content and quality. This way, comments are consolidated and delivered to the author and approver in a standard format.

Reviews are often conducted in order to

• Correct an error in the document and/or product
• Prevent an error from occurring
• Update or clarify information
• Validate a document for use (e.g. select documents for use in connection with a project, product, contract, or other application)

Everyone benefits from clearly identifying changes in documentation during the course of the review cycle. Reviewers and approvers can easily identify what has changed, while auditors can focus on the new provisions. Change initiators can verify that their proposed changes were used as intended.

Methods for identifying changes include:

• Sidelining, underlining, bolding, or similar techniques
• A change record within the document (in the front matter or back matter) denoting the nature of the change
• Appending the change details to the initiating change request

Considerations for the document change process

Whenever a document is revised, its status should signify that it is not identical to the original. Date, letter, number, or combination of issue and revision can identify the status.

Every change to a document should revise the revision. Version 1 may denote the original version. Subsequent changes can be identified as Version 2 or Version 1.1 depending on the extent of the changes. The filename should contain the revision in its title (e.g. "product name/type of document/version"). Create standards for file name conventions of product names, document types, and versions.

In addition, consider staff and related processes:

• Staff should be told the reason for the change. Provide adequate instruction when changes to documents require a change in practice.
• Changes are not complete until everyone whose work is affected understands them and is prepared to implement them when necessary.
• When evaluating changes, assess the impact of the requested change on other areas and initiate corresponding changes to related documents.

Define a policy for approving documents

Approval means that designated authorities agree on the content of the document. Informing and consulting reviewers is not only a courtesy, but also ensures their awareness and approval of documentation decisions. Table 1 shows the roles and responsibilities of the approval process.

Table 1. Roles and responsibilities of the approval process

When the document is approved

Four things should happen once the document is approved:

1. The approver notifies the author.
2. The author changes the status of the document from "Draft" to "Approved."
3. The author sends the approved document, comments, and responses to the Review board, and archives the project in the appropriate directory of the documentation management server.
4. The author files a copy of the approver's notification in the Quality Records directory.

Ensure that documentation is available

A good documentation process makes the appropriate documentation available when and where the work is performed. Appropriate access rights should maintain both public access and security for classified information.

Summary

A defined document management procedure saves time and effort even as it improves quality. It means regulating the development, approval, issue, change, distribution, maintenance, use, storage, security, and disposal of documents. Follow these guidelines to improve your organization's document management, and you'll wonder how you ever got anything done and done right.

References

Hoyle, David, (2001), ISO 9000 Quality Systems Handbook (fourth edition), Butterworth-Heinemann.

ISO 9001 (2000), Quality Systems-Model for quality assurance in design, development, production, installation and servicing.