Earlier in the series:

In the previous post, I was talking about various scenarios when data from a database or another structured source can be converted and integrated into DITA. DITA allows you implement a process that works in the opposite direction too: from DITA, you can automatically generate data that can be directly used by software or hardware, such as programming code, RSS feed, table in a database, or a configuration XML file.

So here comes Reason #5:

Reason #5: DITA Lets You Automatically Generate Code for Software and Hardware

Hardware companies, especially in the electronics and semiconductor industry, often use a hardware description language known as VHDL. Using VHDL, engineers describe the behavior and structure of the physical hardware in digital systems. VHDL is often used to model the design and simulate the behavior of complex systems before they are made into actual hardware.

As any programming language, VHDL is well structured and has a very specific syntax, constructs, and rules.

On the other had, requirements documentation of hardware companies typically includes a lot of well-structured data (which is quite often represented in a tabular format) that describe registers, interfaces, and other components of the system.

A quite typical scenario starts with writing the requirements, including definitions of various components, by a system architect. Once the requirements are passed through the stakeholders and approved, engineers begin to describe them in VHDL. Instead, because both DITA and VHDL offer a well-structured way to describe data, a significant amount of VHDL code can be generated automatically directly from DITA. The automated generation can save time and ensure that the VHDL code is always synchronized with the requirements documentation.

Telecommunication companies whose solutions are based on well-structured protocols for data exchange can also benefit from using DITA for requirements. DITA can be used not just to describe the structure of a message in a requirements document, but also to generate the programming code that creates this message or maybe even build the message itself (especially, when the message is in an XML format too, like SOAP messages). Again, this ensures that the message is created in exactly the same way as it is described in the requirements documents.

Similarly, you can populate a database or generate a configuration XML file used by your software or hardware from DITA.

Because DITA is all about structure, the DITA content that you want to use to generate a programming code or populate a database, doesn’t event have to be a separate DITA topic. For example, if you are in telecom and describing the contents of a SOAP message using a table, you may have a regular narrative surrounding the table. It would be enough that the table (or perhaps its individual rows or cells) has an ID. Using this ID,the required information can be easily retrieved, parsed, and processed as you need.

The advantages of using DITA as a source for both requirements documents and programming code are quite clear:

  • The requirements documents and actual implementation are always synchronized. If a requirement is updated, the programming code can be automatically re-generated.
  • Less time is required for implementation because part of it is now created automatically from DITA
  • DITA can serve as a front-end for generating a programming code and doing simulations. For example, a system architect in a hardware company doesn’t have to actually write a VHDL code. Instead, the architect can generate it from the requirements.

Leave a Reply

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