top of page

Automate It!

Updated: Feb 28

So you are in DITA. This means you can reuse and profile content, produce multiple outputs from the single source, reduce translation costs, and enforce consistency. It seems like you've reached your goals or, at least, is going to reach them in the near future. It's a good opportunity to think now about how DITA can leverage what you've already done. DITA helps you go far beyond content reuse and other often cited use cases. Because it is a structured content format, everything you write in DITA makes the content readable not only by humans, but also by machines. This opens virtually unlimited possibilities for automation of content assembly, generation, and aggregation. Here are some examples of how DITA content can be automated.

Automated documentation assembly Industries, like aerospace, vehicles, and machinery, deal with complex, highly customizable and configurable machines. When different customers receive a different configuration of the machine, how can you ensure that the product documentation adequately reflects a specific product configuration? In one of the projects we've implemented for an aircraft maker, DITAToo automatically aligns flight operations documentation to a specific modification of the aircraft based on the aircraft configuration. The solution involves an automated assembly engine that puts together individual pieces of information (checklists, procedures, technical specifications, and so on) tailored to a specific configuration using:

  • A configuration database where information about all possible configurations is stored

  • Metadata that defines the conditions when a piece of content is applicable to a specific configuration

  • Content enriched with semantic markup that enables the assembly engine to recognize the semantic role of each piece of content and process it accordingly.

A similar method is used to automatically assemble product documentation based on a bill of materials, customer's order or any other structured input.

Dynamic transformation of content representation

Structured content lets you not only produce multiple output formats, like PDF or HTML, from the same source. It also lets you change the way the content is represented on-the-fly. For example, complex technical procedures can be automatically transformed to flowcharts.

One of our customers makes large industrial printers with complex maintenance and troubleshooting procedures. They vary for different flavors and configurations. We've implemented a solution that automatically creates interactive flowcharts from procedures. The flowcharts visualize complex processes and help engineers faster understand what needs to be done.

Similarly, business process diagrams and architecture diagrams can be automatically generated from the information presented in tables.

Automated generation of system architecture diagrams

Suppose you are part of a team that documents a complex product. The product consists of multiple components, and each component is assigned to a certain technical writer or a group of writers.

Each writer knows everything about the components assigned to them and has a general knowledge about other components. Someone (perhaps, a team lead) needs to put individual pieces of information written by different writers together and describe how the system works as a whole. At this point, the team lead needs to write an overview that at the very least includes a system diagram and a brief description of the components depicted on the diagram.

As long as the diagram is created just once without any need for updates, it's not a problem. The problem arises when this diagram needs to be updated because a component is changed, a new component is introduced, or maybe after an existing component became obsolete. Or when there are multiple flavors of the product, and each flavor includes a slightly different set of components, or in each product flavor, the components interact differently.

In this case, re-drawing the diagram or creating multiple variations of the diagram might become an expensive and time-consuming challenge.

With DITA, such a diagram can be generated automatically. For example, we've built a solution that:

  1. Searches the content repository for pieces of information required for a specific product.

  2. Generates a system diagram that shows how major components interact with each other.

  3. Creates a table with a brief description of each component.

  4. Creates a DITA topic that includes the diagram and the table.

When something changes in the components, you just need to re-run the generation process.

Requirements and test documents generation

Development of a new product usually begins with writing functional requirements. Each requirement needs to be accompanied by a test scenario. Without test scenarios, the QA team will not be able to know how to verify whether the requirement is properly implemented.

From the document that contains both requirements and test cases for each requirement, other documents for other purposes and audiences can be automatically produced:

  • Requirements document for the developers (they don't care about tests)

  • Test cases document for the QA team (they don't care about how the requirements are implemented).

73 views0 comments

Recent Posts

See All
bottom of page