Introduction

Custom engineered equipment requires comprehensive user instructions, manuals and guides for proper installation, commissioning, operation, maintenance, repair and servicing. Custom equipment is typically used in regulatory-driven, mission-critical and safety/risk-centric applications. To mitigate these risks, comprehensive user documentation is a must.

Good user documentation is created in a structured manner by contributors from multiple levels of technical expertise. Creation of this type of documentation is a significant technical undertaking and should not be considered an administrative exercise.

This article provides an overview of major considerations and key best practices for developing user documentation and is based on the author’s experience and recognized industry standards in this area.

Planning

User documentation development should start with the end in mind. First, create a multi-level Table of Contents (ToC) as the basis for document development (it can be revised during development). A typical equipment installation and user manual, depending on complexity, could contain the following topics:

Document and Equipment Information – This section typically contains document scope, system overview, operational modes, controls overview and other pertinent system details
Reference Documentation – This section contains all technical references and documentation associated with the equipment installation and use
Safety – This section typically contains information regarding warnings/cautions/notes, personnel qualifications, general safety precautions, work area safety and environmental precautions/considerations
Installation – This section typically contains installation-related information such as scope, responsibility, relevant documentation, prerequisites, equipment handling, assembly preparation, piping requirements including equipment interface, electrical interconnect and on-site assembly
System Overview – This section, unless created as a separate project document, contains an overview of the system and what is is designed to do
Pre-Commissioning – This section contains work checklists and prerequisites governing the pre-commissioning and may include topic such as installation, FAT outstanding punch list, certificates (compliance, regulatory, etc.), databook review, product design compliance, cable & piping interconnect, test equipment calibration, motor rotation, spares, falling object protection, site safety systems, personnel training, lifting appliance certification, utility verification, equipment grounding and vessel controls interface and safety interlocks
Commissioning – This section typically contains information related to system power up, system functional verification (equipment and safety interlocks), controls input/output verification, system shutdown, system operation, pre-start checks, regulatory requirement related to operation and control interfaces/philosophy/interlocks
System Operating Instructions – This section details the requirements for system power and controls check, modes of operation, ancillary equipment operation, regulatory operating documentation and shutdown/storage
Maintenance – This section typically contains manufacturer’s maintenance recommendations, regulatory recommendations, routine and scheduled maintenance, component inspection and repair details (engineered and purchased), troubleshooting, recommended spares and environmental/recycling
Service and Spares Contact Information – This section provides the manufacturer’s contact info for sales, engineering, services and spares

Content Compilation

Content compilation is the next step after ToC development. Content is derived from design and project documents and specifications, regulatory rules, bought-out component documentation, subject matter expert (SME) interviews, manufacturing records, and perhaps other sources. This part of the development process is critical and should not be rushed. Data and personnel availability and project schedules will be key drivers during this work.

Content compilation is a collection of facts about a particular subject area and typically contains several elements such as paragraphs of text, lists, tables, graphics, charts and figures, all with the intent of developing, organizing and effectively communicating information, ideas and conclusions relating to installation, commissioning, operation and maintenance. This step requires professional writing and editing skills to produce useable and technically comprehensive content.

Below the ToC, develop and assemble the content into the document body and edit further for readability, grammar, punctuation, spelling and technical correctness. Except where specific technical requirements must be met or explained, the content should be understandable by equipment installation and operation personnel. This is not an easy task.

Content Creation Best Practices – by topic

Writing Style

Topic organization must be easy to follow
Document must have consistent structure and terminology in the display of numbers, units of measure, figures and tables
All textual content should be relevant to topic discussion
The topic discussion should be culturally neutral and clear, if translated into other languages
Any language translations should be done by a licensed and insured translator who is technically familiar with the document content
Topics should be as brief as possible but explain the topic completely
Industry terms may be used if recognized by and familiar to the reader
Only use quotation marks for actual quotes or titles of papers. For non-quoted content, use italics instead of underline, bold or quotation marks
Structure the document style to be understandable to the reader

Document Software and Format

MS Word software is recommended to develop most user documentation
The complexity of desktop publishing software limits the number of untrained readers that can copy or edit the content for use on other projects or documents
Make and use a Word template containing all formatting (it can be used to create other documents)
Set up MS Word Styles in the template which will automatically format the document layout and styles, thus dramatically reducing the amount of work needed to make comprehensive and understandable documentation
in Word, create a linked Table of Contents (ToC), plus List of Tables and List of Figures, if desired
Structure the document with a cover page including title, document number, revision, author, checked by, relevant logos and/or pictures
Pages after the cover page should be numbered and contain document number, revision and title
Content text should be sans serif and no smaller than 10 pt
Set Word dictionary to US English for documents created for use in the US
Avoid landscape orientation for graphics or tables, unless absolutely necessary
Any document converted to pdf should be text searchable
PDF documents should open with bookmark pane and pages showing.
The bookmark pane will auto-populate during the pdf conversion (if using Adobe Acrobat) for the conversion from Word

Grammar

Limit the use of passive voice (20 to 25% max – lower if possible)
Make explanations complete and concise – avoid verbosity
Avoid the use of slang, jargon, and other regional or local vernacular
Avoid the use of contractions
Avoid first person personal pronouns (you and I)
Third person pronouns (it and they) are acceptable
Avoid fragmented or run-on sentences
Be specific and avoid using inference when developing technical documentation
Use consistent verb tense

Document Readability

Avoid full text justification – this practice causes uneven spacing of words and decreases document readability
ToC should show 3 levels maximum
Document should be limited to 5 levels
Spell acronyms out at first use, or create a glossary near the beginning of the document
Avoid text wrapping around graphics or tables
Text paragraphs are normally not numbered
Other than in graphics, limit the use of color
All lists should have introductory text followed by a colon and bullet or number each list item

Units of Measure

Units of measure (UoM) are abbreviated when used with a number in content text
A unit of measure is a singular term (e.g., 10 bbl, not 10 bbls)
UoMs can be USC or SI or both
Use / (forward slash), not per in UoMs
For numbers in UoMs, use super- or subscript as necessary
Mathematical equations should use mathematical symbols and not their word definition (E.g., P=m/v, not density=mass/volume). Each equation term should be defined
Ranges of numbers are separated by the word to (e.g.,10 psi to 20 psi, not 10 – 20 psi)

Graphics

Pictures, tables, charts may be exported from their source software and sized and/or annotated in various graphic software prior to insertion into the user documentation
To avoid document bloat, when sizing and/or annotating graphics, be sure to save the image file to be inserted at no more than 200 dpi resolution
All insertable graphics should not have to be resized or edited after insertion. All graphics fonts should be the same type and size as the content fonts
All graphics must have a figure number and title and be referenced in the content text. Figure or table number and title must be on same page as graphic
Do not edit graphics in Word – use the graphic software
Additions to graphics in Word can potentially move when editing elsewhere in the document
If drawings are necessary in the document, they should be inserted as converted jpg or png files
Document page sizes can be increased or reoriented for drawing placement (see sections & page breaks in Word)
If annotating graphics that will be translated to other languages, consider using only letters, number and symbols in the graphic with a text legend defining the specific graphic annotations – this avoids double editing of the graphic

Author’s Note

Development of professional documentation is a complex topic with multiple variables, guidelines and recommended practices. This article was written to provide an overview of only the most relevant topics involved in product user documentation development. There are a number of the author’s blog articles and white papers located here, which directly relate to documentation development. Should the reader have questions on this topic or need technical document development support, please contact the author at [email protected].

DEVELOPMENT of EQUIPMENT USER DOCUMENTATION