166 IEEE TRANSACTIONS ON PROFESSIONAL COMMUNICATION, VOL. FC-26, NO. 4, DECEMBER 1983

Planning a Company Program for Technical Documentation

JOHN MASHBURN AND JANICE VANTREASE

Abstract—This paper presents a process for planning a company's overall approach to technical documentation. A hierarchical "docu­ment tree" is used which guides the company to set policies, develop standards, write procedures, and produce drawings and manuals in a coordinated fashion. Using this system, each item that is produced becomes part of an accumulating body of documentation that im­proves the efficiency of management, production, and contract fulfill­ment. The program for technical documentation will support the company's quality assurance program.

IN many of today's fast-moving, technology-based com­panies, the many technical documents used and produced

by the company are not seen as part of an integrated pro­gram. In general, a technical documentation program is the result of organizing (1) a company's policies and proce­dures, (2) the standards adhered to by the company, and (3) government regulations covering its activities into an inte­grated, coherent system. Technical documents are devel­oped by engineering and administrative personnel in the company as a secondary function while they concentrate on attaining other goals, such as debugging computer pro­grams. These people face barriers to their efforts to produce good technical documents that are clear and easy to under­stand. We examine those barriers and present a process for integrating the company's efforts, so that workers can know their part in the overall program and the proper resources can be devoted to each task. Typical situations in industry are drawn from the experiences of the authors, and the solutions presented draw upon the nuclear industry's methods and quality assurance practices.

Suppose a systems analyst is brought in toward the end of a project to produce a lengthy software user's manual. The analyst must become familiar with the user's needs (e.g., previous experience and level of sophistication) and the software product itself. This is often a lengthy task involv­ing many questions such as, Is the software in final form or will changes occur during the writing, editing, and ap­proval cycle of the manual? Are there contract require­ments that, due to other pressing concerns, no one has been concerned about, and which may be overlooked unless a specific review is made for manual requirements? Are there industry or company standards that apply to the product or to the manuals? If so, how does one become aware of them, and where can one obtain a copy? The list of questions can

Received May 17, 1983; revised September 6, 1983. The authors are consulting engineers: John Mashburn is with LTM

Consultants, 238 Peters Road, Knoxville, TN 37923; (615) 693-0485. Janice Vantrease is with H&R Technical Associates, 977 Oak Ridge Turnpike, Oak Ridge, TN 37830; (615) 483-0248.

be endless. In another part of the company, there may be a manager trying to set up an appropriate training program for the wiring technicians. How can the manager be sure that the program will meet the requirements of the company's quality assurance program, the needs of the workforce, and the specifications of products that are not yet released from a design group? Compound these programs with people new to the company or new to the job and you have a situation with which some of our technology-based businesses and government agencies have become familiar. These exam­ples illustrate the major barriers to good technical docu­mentation: lack of knowledge, inability to locate needed resources, and failure to disseminate information within the company.

A company's program for technical documentation should include provisions for engineering drawings, engineering change notices, installation instructions, shop fabrication instructions, operation and maintenance manuals, user guides, etc. However, these are the final tier in a hierarchy of documents that begins with government regulations, company policies, and standards. Other layers include de­sign criteria, contract requirements, market studies, training documents, and procedures. There may be still others in an organization and certainly the treatment and emphasis vary according to the needs of each type of business or agency.

MARKETING SIGNIFICANCE OF DELIVERABLE DOCUMENTS

After a product is designed, the documents to be used by the customer for installation and maintenance, operation, test­ing, and training must be produced. At this point the sched­ule for delivery of the product may be pressing. The de­signers may be involved in last-minute debugging. Often no one has really given much thought to the documents. To the technical people usually assigned the responsibility for document development, these documents are of secondary importance. Yet the documents are vital to the customer's ability to use the product effectively and to the supplier's sales and marketing program. A typical company gets a significant percentage of its business from repeat orders, and technical documents can have great influence on repeat orders. For example, not every supplier is even aware that people who never see the product decide on its purchase according to their impression of the supplier's instruction manuals and drawings. Purchasing agents, headquarters en­gineers, and administrative personnel in large and complex organizations often fall into this category.

0361-1434/83/1200-0166S01.00 © 1983 IEEE

MASHBURN AND VANTREASE: PLANNING A COMPANY PROGRAM 167

Since sales and marketing needs are served by the deliver­able documents, they should be produced under a program that is supervised in part by the sales and marketing arm of the company. The standards and procedures used in the writing, graphics, reproduction, and dissemination of docu­ments must be compatible with the plans of the company for sales and marketing documents. Special expertise is re­quired to produce and revise the documents to meet all the needs.

of similar tasks. Some industries are required to perform activities by written procedures. For example, activities affecting the quality of a nuclear power plant must be prescribed by documented instructions, procedures, or drawings of a type appropriate to the circumstances, and activities must be accomplished in accordance with those instructions, procedures, or drawings.

Contract Requirements

THE DOCUMENT TREE

A good way to begin organizing the overall technical docu­mentation program is to chart the types of documents in a manner that shows their relationships. Figure 1 is an ex­ample of a document tree which might apply to a commer­cial high-technology manufacturer. The company is as­sumed to have two modes of operations, one for regular production and one for contract work. A company program for technical documentation consists of the upper tiers of the document tree through procedures: the regulations applica­ble to or used in the company's technical documents, the policies applicable to documents, the internal and external standards, and the procedures governing the production, dissemination, and use of technical documents. Each ele­ment in the document tree is explained in the following paragraphs.

Government Regulations All activities are subject to external controls and limits. For example, government regulations affect every industry in some way. Two examples of agencies that have a far-reach­ing effect are the Environmental Protection Agency and the Nuclear Regulatory Commission. Thus, government regula­tions are at the top of the tree.

Company Policies Company policies form the next level of the document tree hierarchy. Written policy statements should be produced for major areas of an organization's work. They should be kept up to date by periodic review and made widely available for guidance as lower-tier documents are developed and busi­ness decisions are made from day to day within the com­pany. Not all organizations do this, so this may be the first step in the process of improving the documentation pro­gram.

Standards Company standards may not exist, but in most industries there are external standards that are used and need to be addressed by the documentation program. The adoption of standards, making them available to individuals doing the work, and identifying needs for internal standards are all functions of the technical documentation program.

Procedures Written procedures are needed in almost every organization to instruct workers and to ensure consistency in the products

This branch of the tree may not apply if the organization has no contract work. There is a good chance, though, that these considerations apply to suppliers and it might behoove the contracting officer to become familiar with the recommen­dations for use in getting efficient performance from ven­dors. When work is being performed under contract to an outside entity, care must be taken to review the company's existing technical documents against the requirements of the contract because there can be wide variation in the terms of the contracts, even from the same source. When standards documents are invoked by the contract, it is essential to acquire the standards and ascertain whether they are com­plied with by the company's procedures. The contract re­view is needed to guide not only the engineering and fabri­cation work but also the preparation of technical documents for delivery under the contract. The technical documents often include installation instructions, operation and main­tenance manuals, test plans and procedures, and user guides.

Government regulations

Company policies

Standards, external and

internal

Procedures

C O N T R A C T WORK REGULAR PRODUCTION

Contract requirements

Market studies

Project criteria

Product specifications

Project specifications

Drawings and instructions

Internal working

documents

Inspections and tests

Deliverable documents

Fig. 1. Document tree for a high-technology manufacturer.

168 IEEE TRANSACTIONS ON PROFESSIONAL COMMUNICATION, VOL. PC-26, NO. 4, DECEMBER 1983

Project Criteria If the project is relatively complicated, a criteria document should establish the guidelines and ground rules for detailed development of specifications, drawings, equipment, etc. For simple or repetitive work, this step is not needed.

Project Specifications In some cases, the contract may contain specifications of sufficient detail to directly support product design. As a rule, however, the supplier benefits by writing a project specification that is tailored to the needs of the design team and getting it reconciled to the purchaser's expectations. In this way, if there are options not understood or properly communicated in the purchaser's specification, they can still be resolved at the beginning of the project. The speci­fication should guide the designers in matters of quantity, quality, options, standards that apply, and exceptions to company or industry-common practices. Physical dimen­sions, environmental conditions, response times, power supply, and other information applicable to the products should be included.

Internal Working Documents Drawings for fabrication and assembly, purchase orders for subvendor items, shop orders, work instructions, bills of material, computer programs, and project schedules are items that are already in use in many companies. The im­portance of documents higher in the tree is to ensure that the final working documents are reliable and accurate interpre­tations of the customer's requirements and management's intentions.

Market Studies This branch of the document tree is for activities initiated by the organization rather than by a contract. Assembly line products, consumer services, and ventures fall into this category. Since the work is not performed primarily to a contract, determination of user requirements is a prerequi­site to this branch of the tree. "Market studies" is a label that can be used for this function; for commercial products, market study is often the basis for product planning. The criteria for design and manufacture are given at this level.

Product Specifications The specifications should guide the designers to achieve a product that is coordinated with the goals identified by the marketing department and provide the basis for product-acceptance tests, advertising, and related product planning. Interfacing can also be stressed as applicable. Limitations on the design should be included, applicable standards should be cited, and departures from company or industry-common practices should be spelled out. Unique and inno­vative features should be communicated carefully.

Drawings and Instructions Drawings and fabrication instructions, bills of material, en­gineering change notices, and employee training courses are

examples of the technical documents most familiar in regu­lar production operations. These are the documents used to control the production of goods. They draw upon the higher-tier documents for coordination with each other and with management's aims.

Inspections and Tests The checks performed on the assembly line, the proof tests on new products, receiving inspections, and even accept­ance checks for the products received by a purchaser are examples of functions described by technical documents. They all depend on the detailed designs having been pre­viously worked out, and they must be updated as design changes are made.

Deliverable Documents Generally, any product or service contract involves some user manuals, drawings, etc. for the customer. These appear at the bottom of the document tree because they depend on everything higher in the chart. In some cases the contract may require interim submittals of the design concept draw­ings, interface details, and qualification test data. Only a disciplined operation in technical document production by the supplier can meet all these needs in an efficient manner.

PROGRAM ASSESSMENT

The first step in an overall improvement plan is to assess the existing program and determine where it needs reinforce­ment or alteration to best serve the company's goals. A document tree should be constructed similar to the one in this paper but tailored to the actual company documents. The review can be aided by a checklist reflecting the pre­conceived ideals of an educated reviewer as to what the company program should contain. This helps discover holes in the program where subject areas have not been addressed. Whatever the review technique, it should result in a report that reflects objectivity—a comparison to either an expert's model, a similar organization, or an industry-typical pro­gram. Conclusions should be drawn by the reviewer as to the effectiveness of the program in implementing manage­ment directives, in communicating the necessary informa­tion to each level, and in getting effective lower-tier and deliverable documents produced and in use efficiently and on schedule.

PROGRAM CONTROL

Following the assessment, a regular review and improve­ment plan should be instituted for the technical documenta­tion program. The subject areas omitted from upper-tier documents may take time to institute because any organiza­tion's resources normally have to be devoted to close sup­port of the main products, and the upper tiers are indirect facilitating and controlling items. The use of regular re­views permits progress to be made gradually, if necessary, and also permits incorporation of new information as time passes and circumstances change. If the organization has a

MASHBURN AND VANTREASE: PLANNING A COMPANY PROGRAM 169

formal quality assurance program, certain of the technical documents should be under the purview of quality assurance and will of necessity be upgraded and reviewed periodically as part of the quality assurance function. If the organization has a shortage of experienced or available personnel to upgrade the technical documents, it may have an even greater problem obtaining resources to assess the program and identify improvements needed. This is not a task for a novice because the judgment and experience of the reviewer are key ingredients in spotting omissions of significance, and important management decisions need to be based on the review. Outside consultants, teams of technical writers and engineers, and experienced managers within a company are possible candidates for the review function. Which is best depends on the organization, its experience in the area of business concerned, and the quality of the existing pro­gram. Every effort must be made to ensure the independ­ence and objectivity of the reviewers. The review should not be left up to those who normally are directly responsible for the program. This independence is a fundamental principle of quality assurance. Since every technical organization

produces technical documents continually, a possible start­ing point in locating either outside consultants or in-house expertise is to examine the materials already in use and inquire about the authorship of the better items.

SUMMARY

The barriers to good technical documentation can be over­come by a company program that organizes the entire hier­archy of technical documents involved. The company may find that some of the program areas are weak and by strengthening them it can reduce the ambiguity and lack of direction that hinder workers producing and using the docu­ments. There should be a comprehensive review of the company situation at the outset by an independent team to get the program started. Then periodic reviews will keep the program current. An important benefit to be realized under the organized program is the assignment of appropriate resources to each task—for example, the involvement of persons with marketing or advertising expertise in produc­ing documents for delivery to customers.