DITAworks in Software Development

During the journey from an idea to a finished software product, documentation can often become an afterthought, necessary but a non-core process, and a tedious one at that. But a closer look can tell us about the value of effective and meticulous documentation; reports, manuals, learning materials, guides, and several other major types of documentation provide the basis necessary for making a software product successful.

As a rule, technical writers write documentation. But for them, the process of actually writing the documentation is only a small part of their actual work. They also engage in management and maintenance of the documentation which subsequently includes modifying core fragments across different versions, revisions, and copies. These processes tend to take a lot of time and manpower to execute. And as the amount of documentation grows, so does the maintenance cost and the error rate. The DITA standard is aimed to solve most, if not all, of these problems.

What is DITA?
DITA (short for Darwin Information Typing Architecture) is an XML standard/informational architecture used to organize documents using the single source principle. What this means is that the end document consists of numerous repeatedly used “core” components which are reused in a wide array of documents at the same time. This approach is ideally suited to create manuals, learning materials, online help, and other documentation, all the while maintaining a single, controlled source. DITA helps create content adapted for different target audiences, product variations, and markets.

How does DITAworks help in software documentation?
Let us take a hypothetical company which develops its own software product in the area of cloud server control. The documentation for this product must come in three languages and for three different audiences (users, administrators, developers). Additionally, separate documentation versions for different system types have to be supported. The documentation must be available in PDF, Online Help, and Eclipse Help formats. Overall over 100 different publishing variants!

Before implementing DITAworks, this extensive documentation was stored as separate MS Word files, each requiring to be converted into different formats by hand. Due to numerous repeating content segments across different documents, editors were forced to bring repeating content up to date in all the documents where it was present. This inevitably led to errors and lowered the overall quality of the documentation. Moreover, the translation into required languages was conducted one document at a time, which proved to be quite expensive.

After implementing the single source approach, the core content is now stored in DITAworks only once, dramatically lowering the man hours necessary to keep it up to date and simultaneously raising the quality of all the documentation. Translation costs were substantially reduced. The content geared for different audiences, product versions and languages in all the required formats is now generated automatically during product assembly. The documentation and the software product are now stored in the same version control repository, which made managing different versions significantly easier.

Conclusion
DITAworks offers an entirely new way of working with documentation. It gives technical writers more flexibility and control not only over how they write documentation, but how they assemble and subsequently manage it. It gives management the tools to easily control the flow of documentation, reducing the editing work and thus, reducing the error rate. It significantly reduces costs on all levels of documentation lifecycle.

For further information about our DITA solution for the software industry or to request a personal demo on the subject, please contact us.

Categorised in: Blog