The Underestimated Potential
In the beginning we focused on delivering the technical documentation as a structured document (SGML/XML) as well as a “readable” PDF for the end user. But our technical writers soon discovered that an authoring environment is needed to efficiently and consistently create technical documentation.
SGML documentation in accordance with ATA iSpec 2200 includes about 25-30% more information than standard DTP-oriented documentation. This additional information is not visible in the PDF because it is meta information required for documentation management in a repository. In XML documentation according to the latest S1000D standard, about 25% more meta information is included in the different data modules than in ATA iSpec 2200 documents or 50% more information compared to standard DTP-oriented documentation. In addition, there are the changes of specifications or legal aspects that usually make the documentation even more complex over a certain period of time.
The structured documentation alone would probably increase the documentation costs by 50% if the potential of this structuring method is not used. Similar to a relational data base, all data elements including their attributes can be directly addressed. The following video exemplifies that principle:
This method of directly addressing data elements offers a huge potential for the automation of the technical documentation processes. We have consequently implemented this method in the ARDOS Author software package. Through the constant dialogue between our software developers and our technical writing team, a wide range of functions were developed that not only support the daily work of the technical writer but also help to reduce costs. It should also be mentioned that the quality is significantly increased through the automated processes. Documents that had to be created and later checked through arduous “manual labor” can now be generated with the aid of automated processes.
The following overview and the video show which functions the ARDOS Author offers:
- Usage of SGML/XML structures which are, unlike S1000D and iSpec DTDs, “designed” for the principle of publication (S1000D/iSpec primarily for the data exchange)
- “Enhanced” copying – when data is copied from other sources (similar manuals, page blocks, tasks, data modules etc.), the data is “cleaned up” at the same time: revision markers are removed for the new manual/data module, meta data is corrected, inheritance of meta data is included.
- Mechanism for the selection of function codes or information codes including an informative presentation (codes are not assigned in a cryptic way, e.g. 870 – Description)
- Fully automated assignment of keys, IDs and sequence numbers according to defined and customizable schemata
- Intelligent import options for DPL graphics. The DPL graphics are imported in a batch process, i.e. several graphics including their sheets are inserted to the correct position.
- “Bulk” import of graphics and their respective sheets to the desired position in the manual (e.g. several hundred graphics, each with 1- … sheets with a few clicks)
- Optimized referencing of graphics, tables and other anchor elements. The elements, which can be filtered as well, are selected in a separate window.
- Processing and changing of already existing references with only a few clicks.
- Inserting effectivities (or applicabilities according to S1000D) including a TOP-DOWN inheritance/reduction
- Inserting pre-defined templates with one click or creating new templates
- Excel import interface with variable definition. That way the otherwise extensive transfer of the table information can be carried out with only a few clicks. This function may not be very relevant for standard text processing but it saves a lot of time and effort for documentations in SGML/XML.
and much more!