Technical Documentation Done Right

Technical Documentation Done Right

Consider the following product failures due to poor documentation:

  • A scalpel used for emergency umbilical vein catheter placement posed a safety risk due to poor usage documentation
  • A heart assist pump was recalled because its instructions required updating and were out of date
  • A surgical procedure pack mislabeled its Lidocaine dose (labeled as 1% as opposed to the proper 0.5%)

The reasons for poor documentation or documentation failure are varied but may include one or more of the following:

  • Outdated documentation – documenting the product stopped while design iterations, revisions, and updates continued
  • Poorly structured or unstructured documentation – hard to navigate – documents are created in an ad-hoc fashion with no overlying structure or cohesion
  • Too much detail – not enough detail or missing detail on who your audience is or what information, instructions, and warnings are needed

Whatever the reasons, poor documentation, documentation that misses the mark, or outdated documentation can lead to product recalls, failure in the marketplace, and costly audits from governing entities. If you have recently experienced any of the above, or are considering ways to harmonize documentation authoring across teams and business units, or realize managing change within technical documents is critical to the creation of effective documentation - here are five strategies to consider:

  1. Control product data as content while conforming to a document schema
  2. Extend schemas, styles, and authoring tools to suit your business
  3. Achieve traceability to the latest product data with dynamic links
  4. Control change with flexible processes, concurrent with product configuration management
  5. Publish from a single source to multiple document layouts

Your design processes produce product data, a lot of data. But it needs to be controlled and contained. It can’t be held in spreadsheets, ad-hoc authoring environments, or simply kept in the memories of design individuals. It needs to be in a formal Product Lifecycle Management (PLM) platform where it can be input and accessed by all members of the product team. Then it must be structured by a defined schema including what data is captured, how it is to be structured as content, the relationships between data, and how it is to be presented. Data can then be reused in support of multiple use cases, domains, and disciplines. In this environment, document content is validated so that it reflects current product data. This first step is foundational to producing correct and effective documentation.

In too many cases, unfortunately, the schema is being forced on you, the user by the provider. They have generalized it for industrial use, but its origins may have been for some industry with no relationship to yours. You want documents that will conform to your company’s style guides and needs. You are not an OEM supplier for the automotive industry but a product as a service entity for compressed air. You want to be able to define your own structures, create your own schema. You also want to be able to control the authoring process to a degree, which means you need to modify the user interface to accommodate your users, your corporate structures, and your processes. Look for a PLM offering that has easy to use tools for creating document types and the ability to edit schemas and styles. Consider a system that has an extensible user interface framework that can be tailored to control authorship for your environment. Also, look for a system that can readily incorporate industry-standard schemas and styles if required.

If the documents are going to be correct and impactful, then the data and content presented to the reader must be up to date and properly related to other data currently available. If data is simply floating around in the system, but not properly related to other data, it is unlikely that it will be presented to the reader in the right context, and may be misleading, or flat out wrong. You want data that is connected by a Digital Thread across domains and processes. You need to be able to visualize these connections between data and content in a simple manner that is easily navigated. And you want a system that will guarantee the consistency and validity of the connections at the different levels of product maturity. 

The design process is not linear. There are many detours, delays, modifications, and revisions. These are normal and necessary to produce a viable product. This occurs as several domain disciplines have input. It is critical that all this change is under the control of the PLM platform. Change history must be captured as part of the Digital Thread and appropriately and correctly available as content for inclusion in documents. Users must be aware of changes, can comment on and/or approve the changes. Having data under change control results in accurate documents that reflect current PLM data.

Again, your company and your products are unique. You publish documents for different audiences. The maintenance worker on the job site and the end-user nurse using a monitoring system need much of the same information but look at the situation from entirely different viewpoints. A governing agency wants much of the same content but wants it presented in their preferred format. To save time and money you need to be able to publish content from a single source to multiple document layouts and formats. Packaging needs a printed PDF while the maintenance worker wants an Html view of the document on his mobile device. Same information, different format.

Only Aras provides a technical documentation solution that:

  • Controls data as content in a user-defined schema
  • Allows the customization of that schema and authoring environment that conforms to your specific business needs and goals
  • Dynamically links data and content in an automatic Digital Thread
  • While controlling data change ensures data consistency and correctness across the lifecycle
  • Allows the publishing of multiple document layouts from a single source

Your documents, your way. Aras Technical documentation.