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.
Good points, Ellis. DITA also solves the following problems:
• The time and investment needed to develop custom XML schemas and the transformations (and tools) to publish that content. Before DITA, this exercise could take weeks or months. With DITA, you can get started in just a couple of days, there’s no need to reinvent the wheel.
• The time authors spend (waste) on formatting text, developing templates and keeping all those templates up-to-date.
• Software and hardware investments. New major versions of (often) expensive desktop publishing programs and (help) authoring tools are released every two years or so. With a subscription-based licensing model and binary files, you often have no other option than to “go with the flow” and to keep upgrading these tools. With DITA, you can use a variety of editing tools, expensive ones and inexpensive ones, and even different versions of these tools, all in the same company.
• Support. With DITA, you get free and excellent support and advice in various user groups, not just related to how to use a tool, but also on how to structure and organize your content.
Good points, Yves.
I can’t help thinking that the DITA dream is applicable in a limited set of circumstances. It adds a layer of complexity that whilst solving, the problems you both describe, adds a dangerous distraction that plays to a pitfall may technical authors suffer from – becoming enamoured with the tools to the detriment of the outcomes.
Where you say ‘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’
How does DITA help here? Whilst I may be talking about the same pieces of information, it’s likely that I will be talking in a different tone of voice for each, depending if it’s sales, task-based, reference, etc. Genuine question!
Hi Steve
There are other tools that aim to solve the same problems, and they may be a better solution in certain situations. Scriptorium’s unofficial rule of thumb is that an organisation has a business case for structured content (based on localization cost savings) if they have: Ten or more writers, four or more languages, and more than 2,000 pages of content per language.
In a DITA environment, the writing and publishing roles are separated, so it can make it less distracting for writers. Their role is to write.
Regarding re-using information. You can vary the information that precedes a re-usable piece of information, and you can vary what comes after. If it’s task-based information, you can insert extra steps into a procedure, without having to touch the topic containing the standard set of steps. Information such as “The widget supports 200 users” is unlikely to vary across all the different publications.
People talk about up to 30% of content being able to be re-used in an environment such as DITA provides.
Thanks for the reply (I don’t know what the random comma above was about!). My only real world DITA experience was of a project some years ago with two authors on different sides of the Atlantic, one of whom had fallen under the spell of the Next Big Thing. It was inappropriate and a distraction in that case. Is there an element of de-skilling and atomisation in separating out the writing and publishing side do you think?
Many companies have moved from hand coding Web pages to using CMS platforms such as WordPress. That resulted in deskilling, but it also resulted in time being freed up to do more important things than moving an image 3 pixels to the left. Perhaps a DITA based system will do the same.