Developing high-quality documentation is a subtle and complex process comprising many steps. Though the process is represented as a linear continuum, the actual order in which steps occur may vary or overlap.

Define Purpose
Defining the purpose of a documentation project enables the writer to establish a scope of work and to begin to envision the finished product. This step requires profiling the target audience, determining its pre-existing knowledge level, and establishing the needs of the end users. Purposes may include application guidelines, principles of operation, or instructions for assembly, installation, operation, maintenance, troubleshooting, or spare parts. It is also necessary to determine mode or modes of delivery. Documentation is usually provided in the form of manuals constructed in linear fashion, but sometimes it is provided in more dynamic electronic form, as with a content-management system. Decisions regarding delivery platform should be made early, and development tools selected accordingly.

Gather Source Data
A documentation project typically begins in consultation with subject-matter experts (SMEs) – engineers, marketing personnel, assemblers, installers, maintenance personnel, materials management personnel, safety managers, and others. Subject-matter experts are typically too busy doing their own work and lack the level of documentation skills of a professional technical writer. Not being an SME can be an asset, as it is easier for non-SME writer to assume the frame of mind of a typical end user. Source information is also obtained by reviewing engineering drawings and bill structures, observing systems in operation, and even physically disassembling and reassembling devices.

Regardless of how well the purpose has been defined, there is no information to organize until it has been gathered. Once gathered, however, the source information must be digested in light of the communicative purpose in order to organize it to serve that purpose. This step precedes and merges into the step of actual writing.

Writing obviously entails generating text. Though this step is shown as preceding the generation of graphics, it is quite often beneficial to generate graphics first and craft the language afterward. For example, it may help to create a flow diagram of a process to be documented, and then work from the flow diagram to describe the process verbally. I can think verbally and visually in unison, and I typically alternate between writing and generating graphics as I develop a document. In the crafting of document language, the sequencing of topics is refined; the flow of ideas must be logical. It is necessary not only to conform to rules of grammar, but also to observe proper semantic conventions. Depending on the audience, trade jargon, and especially ?house jargon,? may need to be explained.

Generate Graphics
I am very good at visualizing graphics to support the message presented in the text, and I am also adept at executing graphics in a wide range of forms. An accomplished technical illustrator as well, I can generate orthographic, axonometric, and perspective drawings precisely. My training in photography includes optical principles, studio lighting (which is especially important when photographing shiny metallic parts), portraiture, and news, legal, and aerial photography. I am also highly skilled at generating charts, graphs, and process-flow diagrams using a variety of tools.

The process of integrating a document entails assembling the various elements, text and graphics, formatting the document per the style sheet, and setting up indicial data. Internal links between in-text references and captions for tables and figures must also be established and confirmed. Running a spell-check and generating a table of contents and index (if included) are typically the last steps before the document is reviewed.

To ensure that the information is correct and complete and that it fulfills the defined purpose, the completed document must be reviewed by the SMEs who provided source information. Delays often occur in the review process, as SMEs tend to put documents for review on the back burner. As difficult as it is for SMEs to find time to review finished documents, it would be all the more difficult for them to find time to generate documentation in the first place. Yet reviewing documents is a crucial step prior to transferring ownership of the documentation from the technical writer to the client.

If revisions are required, they are made prior to releasing the document.

In the publishing phase, the document is produced in its final form or forms. Documents are typically produced in hard-copy form and in portable document format (PDF) forms. They may also be produced in other electronic forms, such as a content-management database to be accessed via the Internet or a private Intranet. Though backup files are made throughout the development process, file management takes on a special importance at the time of publishing, as version control is a vitally important issue. The current version must be readily identified, and previous versions must also be retained.

© 2012 - Joseph A. Spitzig. All rights reserved.