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

Suggested Reference Documents

The latest editions of the following publications may be useful aids in creating technical documentation:

  • SPE Style Guide
  • SPE Metric Standard
  • Chicago Manual of Style
  • ISO 31-0 Quantities and Units
  • ISO Directives, Part 2 – Rules for the Structure and Drafting of International Standards

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