Ahead of Time
In structured documentation, specific elements and attributes that are required and optional are defined with the aid of DTDs or XML schemata. This ensures a consistent structure of the technical documentation. In addition to these structural requirements, there are a number of textual matters that have to be dealt with in the technical documentation.
Every technical writer would prefer errors, inconsistencies or shortcomings to be already indicated in the writing process of the technical documentation. The disregard of certain rules either defined for the team or by the customer, often goes unnoticed until the final editing phase of the already finished technical documentation, which often consists of several hundred or thousand pages. The correction of such errors is often time consuming. Even in the course of migrating technical documentation, i.e. integrating “external” or “old” documentation to the own systems and/or documentation environments, an analysis of the efforts that can be expected is required.
For all the above-mentioned reasons, a demand exists for tools and features that analyze the technical documentation according to defined rules and also report potential deviations accordingly. Such feature should also be as easy to use as the classic spell checker of a standard text processing software.
In 2005, a few years before the publication of the S1000D BREX – Business Rule Exchange (from version 2.2), we have already implemented such mechanisms in ARDOS with the ARDOS Checker. With the approach of a rule-based check mechanism in 2005, we were most likely ahead of our time. Nowadays such ideas in the area of technical documentation are at least implemented for S1000D. Even though check processes or a check software are not implemented in the pure definition of BREX, but at least the industry has issued a standard from which a set of rules can be specified and exchanged.
For over 10 years now, the ARDOS Checker has been developed and improved constantly to meet the requirements of the technical writers, technical illustrators and the data processors (e.g. generation of IPL/IPD). It also serves as support for the whole writing/editing process as well as for the exchange of such a set of rules. That way the technical writer can carry out a check of the documentation or parts of the documentation to be delivered at any time:
- ARDOS-integrated set of rules for iSpec 2200 documentation
- Compliance with Simplified Technical English
- Check of all meta data including their inheritance in the manual
- Check of completeness (many SGML/XML elements are optional but when they are used in the context, they are often mandatory)
- Validity check
- Usage of data bases (tools, materials etc.)
- Check of graphics (size, title etc.)
- Check of DPL illustrations, parts list and disassembly/assembly
- Check of the whole revision process
- And much more
- S1000D option, check according to BREX rules
- Check according to the respective DEFAULT BREX (S1000D v2.3.1, v4.01 and v4.1)
- Check according to the respective data module defined in BREX (e.g. Airbus BREX)
- Custom BREX check with self-defined business rules
- Own BREXS editor
- API interface for the definition of your own set of rules. This method is recommended when you wish to define "stricter" rules for the team.
- “Simple” XML-based “macro language” for the definition of rules