Newsletter of the East Bay Chapter of STC
March/April 2004

Documentation Management for Dummies

by David Dick and Kathy Bine

David Dick is a Technical Writer for the Society for Worldwide Interbank Financial Telecommunication (SWIFT) in LaHulpe, Belgium.

Kathy Bine documents software solutions for ICF Consulting in Fairfax, VA. She is a member of the Washington, DC chapter of STC.

This article is reprinted from the July/August 2003 issue of The Nor’easter, Northern New England Chapter.

The typical project consists of proposals, plans, meeting minutes, customer requirements, functional requirements, use cases, test plans, design specifications, overall design document, user guides, system administrator guides, installation guides, and training manuals. It may 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.

The goal of documentation management is to ensure:

• 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.

Defining a Documentation Management Strategy

A documentation management strategy should be supported by a procedure that defines the documentation development process, which includes:

• Planning new documents, funding, authorization, establishing need, and so on.
• Preparation of documents, who prepares them, how they are drafted, conventions for test, diagrams, forms, and so on.
• Standards for the format and content of documents, forms, and diagrams.
• Documentation identification conventions.
• Issue notation, draft issues, post approval issues.
• Dating conventions, date of issue, date of approval or date of distribution.
• Document review: who reviews them and evidence that 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.
• Revision of issued comments, requirements for revision, who approves the requests, who implements the change.
• 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 security, unauthorized changes, copying, disposal, computer viruses, fire, and theft.
• Document filing, masters, copies, and drafts.

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

Creating a Documentation Review Board

The documentation review board consists of the following members:

• Reviewers are subject matter experts who judge the accuracy of the document and see that it satisfies the intended purpose.
• Authors are the persons who create the document.
• Approvers are the persons who approve the publication of the document.

To avoid extensive lists of reviewers, the Authors and Approvers may select a representative from each area that is responsible for consolidating their team's comments. The nominated reviewer may distribute the document within their team, but they remain responsible for filtering and consolidating feedback before passing it to the author.

Conducting a Documentation Review

The Author sends the document and a document review form to the review board. To avoid a meeting, distribute the document (via the document management server) to the review board and provide a standard comment sheet on which to add comments and suggestions. In this approach, comments are easily consolidated and given to the Author and Approver for review and response.

When Is It Necessary?

The document review ensures that the appropriate people check information for correctness and that their comments are addressed.

Reviews are conducted when:

• Taking remedial action to correct an error in the document and/or product.
• Taking corrective action to prevent an error from occurring.
• Taking preventive action to prevent occurrence of an error.
• Updating or clarifying information.
• Validating a document for use (e.g., selecting documents for use in connection with a project, product, contract, or other application).

Benefits of Identifying Changes

• Reviewers and Approvers easily identify what has changed and expedite the approval process.
• Auditors can easily identify what has changed and focus on the new provisions.
• Change initiators can easily identify what has changed and verify whether their proposed changes were used as intended.

Methods for Identifying Changes

• Sidelining, underlining, boldfacing, or similar technique.
• A change record within the document (at front or back) denoting the nature of the change.
• Appending the change details to the initiating change request.

Considerations

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

Whenever a document is revised, its status changes to 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 be reflected in a version number. 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>. You will want to create standards for file naming conventions of product names, document types, and versions.

Define a Policy for Approving Documents

Approval means that designated authorities have agreed on the content of the document before making the document available for use. The goal is to ensure that a panel of Reviewers has evaluated the documents. Informing and consulting the Reviewers is not only a courtesy, but also ensures that they are aware of decisions taken, why, and the opportunity to reply. The following table shows the roles and responsibilities of the approval process.

When the document is approved:

• the Approver sends an e-mail to the Author.
• the Author changes the status of the document from Draft to Approved.
• the Author sends the approved document, comments, and responses to the review board, and archives it in the appropriate directory of the documentation management server.
• a copy of the e-mail from the Approver is filed by the Author in the Quality Records directory.

Ensure that Documentation Is Available

Documentation should be archived on a documentation management server which users have access to. User access rights that reflect security considerations should be set up on a per user basis.

Summary

A defined procedure saves time and effort, and improves quality. It means regulating the development, approval, issue, change, distribution, maintenance, use, storage, security, and disposal of documents to ensure quality. Follow these guidelines to improve your organization’s documentation management process, and you’ll wonder how you ever got anything done correctly before now.

References

• Hoyle, David, (2001), ISO 9000 Quality Systems Handbook (fourth edition), BH
• ISO 9001:2000, Quality Systems—Model for quality assurance in design, development, production, installation and servicing.
  

DMV Home | EBSTC | STC | Contact Us

Helping Make Projects Work | Documentation Management for Dummies | Well Planned is Half Done
Ask Elaine | First Impressions: Resume Tips