DITA, S1000D… What if you have to choose?


You’ve probably already heard of it; you’ve looked into it: DITA and S1000D are streamlined editorial standards that help you improve the management of the production and distribution of your technical publications (user manuals, maintenance manuals, training manuals, technical-sales offers, etc.).

More specifically, the use of these standards means that, if your documentary production is suitable, you can:

  • Significantly increase perceived quality
  • Reduce update costs
  • Reduce translation costs
  • Distribute your publications easily through different channels: paper (and PDF to download), web and mobile

How do they work?

DITA and S1000D are both based on XML, a non-proprietary “text” data recording format that is universally recognized, notably because it accepts all alphabets (European, Asian) and supports easy exchange on a global scale.

What’s more, both S1000D and DITA use a “modular” editing format: documents are made up by assembling documentary units that can be reused in different publishing contexts. The documentary units are reused whenever there is technical commonality (products themselves that are modular), cross-disciplinary aspects (security, legal, design, procedural etc.), shared data (brands, spare parts etc.), and so on.

For each module and within each module, an applicability mechanism manages the variable aspects according to the context in which the publications are distributed: multiple brands, regional specificities, customer specificities, and so forth.

The granularity of the documentary modules, combined with essential writing discipline, leads to the above-mentioned savings and quality increase. As for multi-channel distribution, it requires a good command of distribution formats, both for PDF generation and for conversion to web format (HTML) or to Apps for phones and tablets.

So, DITA or S1000D?

The answer is relatively simple.

S1000D is a set of very precise specifications in terms of the data to be used and the processes to be implemented, in the context of the operation of physical equipment, mainly mechanical, electrical or electronic.

Some industries require the use of S1000D in order to ensure interoperability of information between the different entities involved in the operation, support or even transport of the equipment. These sectors include Defence (air, sea, land), Civil Aeronautics, as well as Rail and Nuclear. All of them operate equipment with a very long service life, where modifications have to be followed very precisely.

To achieve this, S1000D requires that a precise, internationally-approved material division of the equipment is respected.
However, it should be noted that S1000D is difficult to approach, to answer all the problems of the fields concerned, and suffers from a relative lack of flexibility, even if some parameters are adjustable.

S1000D does not include standard tools to generate publications, and, for example, cannot be used efficiently to document software because it is not detailed enough in terms of modularity.
DITA, on the other hand, is a toolbox rather than a specification. It includes standard tools that meet the vast majority of cases, allows for publication, and is the result of a consensus of post-web specialists, unlike S1000D, which is older.

In itself, the DITA standard basically leaves the user relatively “unassisted” compared to S1000D, but in return, DITA has a very high degree of structuring flexibility: DITA would permit “rebuilding” and imitating the S1000D standard, if necessary.

More simply, DITA makes it possible to build the documentation system you need, because it adapts to just about anything, by addition: DITA is designed as a scalable system that retains its interoperability while allowing customization.

If your products and processes are simple, DITA will be simple. If not, DITA will adapt “just enough” to meet your needs efficiently.

On the need for good tools and guidance

A modular documentation project, whether S1000D or DITA, can mobilize 500, 1500 or 5000 documentation units. The totality of the documentary units of an industrial or software company can be counted in tens or even hundreds of thousands of units.

To manage the versions, languages and links in this mass of information, a CCMS (Component Content Management System) is necessary, as soon as the number of document units exceeds a few thousand.

You will be all the more efficient as the tool will adhere to your own processes regarding information-distribution and production, adapt to your data formats, and interface with your existing information management systems.

Given the complexity of S1000D, and the freedom offered by DITA, our specialist support and training services in these standards will be of great benefit to you, whether you want to start your projects or help your company in its digital transformation.

Documentary engineering: what are we talking about?

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.

Posted in Uncategorized