The evolution of documentation
In the past, documentation used to be a manual that had to be provided when the equipment was delivered. Today, its format is mainly electronic. As a result, it is now accessible on the Internet and offers greater interactivity with the end customer. The product user has easier access to the information through dynamic queries and filters.
In the future, documentation will integrate new technologies such as machine learning and virtual reality. In order to adapt to and anticipate these developments, companies’ after-sales departments are rethinking their documentation to improve its quality, facilitate its use and enrich it with new content formats (3D, videos, etc.).
The structured context
The document creation process is framed by a set of rules, called specifications. These specifications come from an internal department of the company or an international organization. In the aeronautical field, for example, certain standards are widespread, such as ATA, S1000D or DITA. They provide at the very least a structure for the documentation, but also rules for writing, exchange, and layout.
For “text” content, the XML format is preferred. The structure is provided as a Doctype (DTD) or XML Schema (XSD) file. For other formats (videos, images, etc.), the specification imposes the rules to be followed.
In addition to the structure, the specifications also control how documents are written. For example, the S1000D standard provides an exchange format for these rules called BREX (Business Rules Exchange). These writing rules will help streamline certain processes, such as the number of steps in a procedure for dismantling an industrial asset.
Another standard called ASD-STE100 (Simplified Technical English) controls the use of the English lexicon for procedures. For example, the standard prohibits the use of the verb “place”, imposing the verb “put”, in order to have consistent sentences.
Standards also exist to restrict the content of graphics to ensure their proper display in visualization tools. This is the case of the WebCGM standard, co-produced by the W3C and OASIS groups, which restricts the use of graphics in CGM format. Since CGM is a format that can be modified at will and free of charge, it is essential to limit the use of its content.
Despite this array of standards, manufacturers often add their own rules to strengthen control over the documentation process.
In the end, when a manufacturer delivers material to end customers, they are quite free to choose the standard they want to follow. On the other hand, an equipment manufacturer who has to deliver to several manufacturers will be obliged to deliver its documentation in compliance with the standard chosen by its customers.
Once the rules have been defined, it is time to produce the technical documentation.
The documentary production process
The trigger
Several events can trigger the process. It can be a matter of creating documentation for new equipment or integrating a modification from a third party (design office, assembly line, authority, etc.) into existing documentation.
The collection of source data and impact analysis
The first step is to retrieve all the documents associated with the modification (plan, 3D data, logistic analysis, assembly range, photos, etc.) and to analyse which elements of the documentation are affected by the modification.
This step allows you to plan the writing, define the delivery dates and choose the people in charge of writing. For example, in ADAM Manager (the content management system especially for document engineering made by 4D Concept), ), it is possible to create a list of empty documents and assign them to a writer.
The writing
To make the work of the writer easier, it must be done in a constrained environment. In this respect, a good tool integrates technical or business controls. Otherwise, the writer refers to a writing guide, which will increase the risk of error. A good writing tool must be easy to use and must guide writers in their work, without blocking them or modifying the content in their place.
If the need arises, the writer can also prepare illustrative mock-ups. An illustrator then uses them to design the graphics in a technical drawing tool (2D or 3D), respecting the standards of the project.
In the production of technical standards, any modification made to an existing document must be traced, so that it is possible to go back and find out about past modifications and their authors.
If the writers are writing sections that are used for different pieces of equipment, they must be able to use the editing tool to assign which pieces of equipment are involved. The aim is to avoid redundancy of information and reduce the risk of inconsistency.
The preview
Before final validation, a check (called the preview) is performed to ensure that the rendering corresponds to the previously written content. The written document is thus processed through the same steps as those carried out during the final publication.
In the ADAM, this preview stage can be launched by the writer at any time during the writing process from within ADAM Author.
The validation
Validation is carried out in several steps to ensure that each document follows the procedure in place.
- A proofreading step is necessary to detect possible errors in the first version of the document.
- An automated validation step, which can be performed in ADAM Data Checker, reduces the risks of poor quality by integrating automated checks.
- Finally, for certain procedures, a validation in real conditions on the equipment must be carried out.
The publication
Once the documentation has been validated, it will be published and delivered to the customer.
During this step, it is mandatory to precisely trace the content delivered to the customer. For instance, it is necessary to list the documents sent and to list the differences between each new version of a document.
Once delivered, a document can no longer be changed. Each change requires a new version to be delivered, which triggers a new document creation cycle, governed by the specifications in force.
Documentation can be delivered in paper (PDF) or electronic (Viewer) documentation format. The customer can also request the raw files (graphics and text), if they wish to integrate them into a new processing chain.
The need to be equipped
The desire to produce more interactive documentation, with an ever-increasing level of service, is pushing producers of technical documentation towards more structured, more modular, but also more complex information.
As a result, it is almost impossible to manage document production without:
- a guided writing workshop;
- a content management system (CMS) with monitoring of publication flows;
- a document control tool;
- a publishing tool with filtering functions.
It is with this in mind that 4D Concept is developing the ADAM suite in order to accompany the document engineering process at every stage.