We’re currently working on updating our DITA Basics training course. It’s likely we’ll offer the course as an self-study online course, a classroom course, and as a live tutor-led course delivered over the Internet. In carrying out this exercise, we realised that there was a need to answer some basic, fundamental, questions. So let’s look at some of one of those: which problems were the creators of DITA trying to solve?
Which problems were the creators of DITA trying to solve?
1. PUBLISHING TO LOTS OF DIFFERENT FORMATS AND VARIATIONS OF THE SAME DOCUMENT
Often with technical documentation, you’ll find the same pieces of information appear in more than one document. For example, it’s likely an overview of a product or a process will appear in a Getting Started guide, a user guide, training courses, the company website and product datasheets. On top of that, it may also appear in customer-specific, budget and premium configurations of the product.
If you need to make a change to that piece of information, all that complexity can result in a considerable amount of time, money and effort.
2. Having consistent documents
In another situation, an organisation may have a standard set of procedures for fire safety. Although the policy should be the same in every location, you may need to vary the information so it includes local maps and emergency numbers.
If you need to change the policy, you may need an efficient way of ensuring the documents at every office location are all updated so they have the same, consistent information.
3. Being able to share and include content from other places
Another challenge can be incorporating content that’s been written by others. For example, if you’re documenting how an offshore oil rig has been constructed, details such as how the kitchens are designed, and how the electricity generators are configured, are likely to come from the suppliers of these items.
Where you may have used a third-level heading (Heading 3) to describe something, they may have used a fourth level (Heading 4). They may describe features in long, multi-topic, chunks of information, where you break your content into lots of small chunks.
These differences can mean that you’re unable to automatically import or include information created by others. It can also lead to a great deal of time and effort if they send you an updated version.
Ideally, you want the information supplied to you to be consistent and compatible with your content.
4. Encouraging/enforcing good writing standards
If you have a team of writers, you don’t want that to result in publications that are written inconsistently. For example, you’re likely to want each function in an API online guide to be consistent when it comes to what types of information are provided, and the order in which the information is described.
Even at a basic level, task-based information (how to do…steps) should be distinguishable from other types of information.
5. Avoid having to translate the same piece of information over and over again
Translation companies generally charge on a “per thousand words translated” basis. If you’ve got lots of documents and/or lots of languages to deal with, this can be an expensive business. Having chunks of information that can be used in lots of different documents reduces the amount of content you need translated – it means you translate it once and re-use it in lots of different situations.
6. Future-proofing content
Documents, or more specifically the content contained within them, might be needed for years and years. The content might be needed to be published into new formats and media – such as HTML5 or something that hasn’t yet even been invented yet.
We want to be able to change the way the content looks in any future published versions easily, and without having to change any of the content. This means the content and the formatting should be separate and distinguishable from each other. It also means the content should be stored in an open standard.
What other problems do you think DITA solves?
You can use the comment box below.