Earlier in the series:

Quite often, the requirements documentation (for example, design documents) include data that is also used by the software or hardware. It might be configuration parameters stored in an XML file from which the software takes them and uses for initialization. Or it could be data on registers (especially in the semiconductor industry) stored in a database from which the software reads them and uses to manage circuit boards. The documentation should describe this information too.

Because this data is stored in a separate location, which has its own lifecycle and owners, making the documentation to be synchronized with the data requires considerable efforts.

So here comes Reason #4:

Reason #4: DITA Lets You Automatically Integrate Data into Content

One of our customers, a big software development company, used XML to describe configuration parameters of their software. The software read the configuration XML file and behaved accordingly. The amount of the configuration parameters was enormous: the XML file included 6,000 parameters, and each new release only increased this number.

The problem was that all these parameters had to be documented. Can you imagine a technical writer copying-and-pasting these parameters from the configuration file to the authoring tool? To make things even worse, engineers updated the configuration file quite regularly so copying-and-pasting was part of the writer’s daily routine.

But to let you feel a real scale of the challenge, think about this: the configuration parameters were also part of the internal requirements and design documentation. This documentation was created mainly by system architects for internal use by other architects, product managers, engineers, and support team. The system architects were not particularly happy wasting time on the copy-and-paste work either, leave alone a bunch of inconsistent and outdated information in the documentation.

We moved their documentation to XML and built a mechanism that parsed the XML configuration file and automatically integrated the configuration parameters into the product and requirements documentation. The data about parameters was rendered into nice looking tables that were easy-to-read and understand.

From now on, every time the configuration file was updated, the relevant documents were automatically updated too. Yet, the authors would have to add some narrative (like descriptions for human readers, for example), but at least they could be sure that the documentation now included up-to-date information and it’s synchronized with the XML configuration file.

In another project, the customer (a semiconductors company) had data about registers and boards stored in a database. This information was part of both user manuals and internal requirements documentation. Just imagine the amount of copy-and-paste work as well as the scale of unsynchronization between the documentation and the information stored in the database.

After the documentation was moved to DITA, we’ve built a solution that retrieved the data from the database, converted it to DITA tables, and integrated them into the documentation. Every time the database was updated, the documentation was automatically updated too.

This is what is so great about DITA. Once you have content in a structured format, you can integrate it with other data whether it’s stored in a database or another XML format. The benefits are obvious:

  • Full synchronization between different sources of information, no room for outdated documentation
  • Effective use of authors’ time – instead of wasting their time on the error-prone copy-and-paste work, they can entirely focus on writing high quality documentation
  • Less time is required to update an existing document or to create a new one

Leave a Reply

Your email address will not be published. Required fields are marked *