DITA Success Story
In 2004, even before DITA was standardized, Comet had already recommended that its customers switch their documentation environment from Word to DITA. A productive environment was up and running after a short three-month implementation period. Even today, this environment remains innovative, stable, and efficient and has proven adaptable to all requirements.
SOPERA GmbH is an open-source service provider dedicated solely to the SOA (service-oriented architecture) strategy. The company emerged from an SOA development unit within Deutsche Post, the latter having begun work on a service-oriented platform (SOP) as early as 2000. Founded in March 2007 and now independent of Deutsche Post, SOPERA GmbH continues to work in close partnership with the logistics player Deutsche Post.
The documentation partner
Comet is a market leader and full-service provider for technical documentation in Germany. The Comet group consists of Comet Computer GmbH and Comet Communication GmbH. We frequently manage the entire documentation process for large-scale projects. Using state-of-the-art technology, we design and implement efficient solutions that are suitable for all types of media.
Since 2003, we have been using DITA to successfully implement the class concept by Sissi Closs in both industry projects and in an academic setting.
SOPERA offers a complete SOA suite. This software was created by an in-house development team at Deutsche Post and relies on open standards and modular components. It is designed as a framework for existing and future services. More than five years of in-depth experience acquired during development and operation of the service-oriented platform (SOP) for the Deutsche Post had gone into SOPERA.
The task was to set up an operational, future-oriented, and efficient documentation environment. For the customer, the environment had to be standards-based, cost-effective, and easy to integrate into the existing open source infrastructure. Within only three months, we had to produce the first manual in this new documentation environment.
We decided to use DITA and structured FrameMaker to streamline the content authoring and production processes.
Since deployment, the system’s performance has been almost flawless. Based on the results of this initial implementation, there were no hesitations about extending the use of DITA.
With the product documentation for its SOA suite, the customer faced the following challenges:
- distributed and parallel implementation with an increasing number of external partners
- varying authors (internal and external)
- increasing number of customers and the demand for publication via the Internet
- demand for different languages
Initial situation 2004
The customer had no internal documentation department at that time, meaning that many authors contributed to the documentation, none of whom were technical writers.
Facing growing challenges, the company’s previous Word-based documentation process could no longer meet the requirements. The customer encountered the following problems:
- a large amount of MS Office documents (xls, doc, ppt) Up to 50 documents existed but there was no clear separation of information.
- high redundancy The same information was repeated in many documents. However, it was not always written in the same way.
- outdated content
- print-oriented structures, with PDF being the only online format
- slow access Users wanted to access information quickly in order to help them do their jobs more efficiently. They wanted to identify the relevant items while setting aside distracting, less relevant content.
In collaboration with external consultants, our customer wanted to reorganize their product documentation from scratch with the objective of developing a documentation strategy in form of a comprehensive management process for the product’s information lifecycle.
While the new process was being implemented, the customer wanted productivity to remain undisturbed. Their documents should continue to be created on time and without generating any additional costs.
Without a content management system
The first stage of the project had to be carried out without content management tools, due to their relatively high cost and the even higher cost of customizing them. There was also the risk of these tools becoming quickly outdated.
In designing a new documentation environment, the customer’s goal was to produce all information from one single source, consolidate all content into this single physical area, and provide a consistent look and feel for the documentation.
Following a comprehensive evaluation, DITA was selected as the best XML architecture for the future-oriented environment although DITA had not yet been standardized when we started.
DITA enables content reuse using well-defined topic types and DITA maps. For example, if information developers want to describe a product feature, they write a DITA concept topic. If other information developers then need to provide the same information, they do not have to rewrite the information but can instead reuse the entire concept topic by including it in another DITA map.
If you work with a variety of suppliers and need to reuse their content, using the same architecture can save you money and, because DITA is an open source standard architecture, there are no proprietary restrictions on using it. Furthermore, if you use DITA, but have different layouts, you can still easily share the content source and generate the information to meet your company styles without high costs.
DITA builds on reliable sources
DITA is not a completely new invention; instead, its XML-based format and topic-oriented structural technique rely on tried and tested methods and techniques. DITA establishes good documentation principles, which have proven themselves time and time again. These principles not only create a basis for confidence for future documentation projects but also enable good technical implementation as well.
DITA is based on topic structures
A typical problem in classic documentation is a descriptive style that tends towards the unclear separation of content. For example, an explanation of a subject contains the definitions of terms and further explanations of other subjects. A subject may contain different content types, in particular explanations and instructions that become mixed-up. This vague structure leads to inaccuracy and renders the reuse of content in various compilations more difficult. This lack of reuse in turn produces unnecessary redundancy with all its related problems.
To work against this problem, the well-known topic-oriented structure, used extensively in the world of online-help, aims to present each subject as a self-standing component, isolated and context-independent. These components are called topics. Successful topic classification means that accuracy can be better checked and that content can be reused more easily.
Until now, technical implementations for topics have only been found in authoring tools. However, these are tool-specific. For the first time, DITA provides an XML-based topic definition that is independent of tools and manufacturers.
DITA provides flexibility
Topics are, as much as possible, created independently from the context so that they can be used in as many places as possible. Context, hierarchy, and relationships are specified in a DITA map when a particular document is produced. The DITA map is similar to a table of contents in an online help system. Using this DITA map, you determine which topics belong to the final document and how the topics relate to each other.
From a collection of “good” topics, documents can be put together as needed, using the appropriate maps for different target groups, purposes, and output media.
DITA supports classification
Topics offer more flexibility but require a higher level of organization. Instead of having fewer chapters, the authors have to plan, manage, find, and properly organize numerous topics. Classification provides a methodical solution. Instead of having to plan each individual topic, you can work out a definition for each topic type, which can then be implemented for each topic. Finding a suitable type is by no means a simple task, but with the help of a good modeling technique, like the class concept (“Klassenkonzept”) from Professor Sissi Closs, it is definitely doable. DITA provides, in addition to the generic topic, the basic types: concept, reference, and task.
DITA is adaptable
XML and topic-orientated structures have never been a guarantee for successful documentation, as proven by many documents and onlinehelp systems. An architecture is only profitable when it matches the content and environment. This matching requires experience, which as a rule, does not come with initial use. It is here that DITA is best prepared. DITA contains specialization as a mechanism and has clear rules so that new types and structures can be defined based on existing ones. An existing function is kept and can be reused. This reuse means that, for the first time, DITA makes it possible to adapt a given architecture to the actual conditions and to gradually optimize it.
DITA provides a methodical and formal framework for successful documentation practices, which is indeed the answer to many of today’s documentation problems. In addition, suitable authoring tools are available. We chose structured FrameMaker as the best solution for authoring and print layout. It is a professional and proven authoring and publishing system, and with it you can create high-quality documents efficiently. Figure 1 illustrates the content framework.
Figure 1: Content Framework
Despite the fact that there was no pre-defined DITA configuration for FrameMaker when we first started, we still had several reasons for choosing this program. With FrameMaker, we could
- generate professional PDF and print output
- create a productive environment in a short time
- adapt layout easily according to requirements
We developed the FrameMaker DITA configuration (edd, template, rules) from scratch, and after only three weeks, we were ready to produce the first documents. This rapid development allowed the customer to evaluate the configuration at an early stage, which in turn gave us flexibility in improving it to meet their needs.
We wrote the content for the first manual while we configured FrameMaker for DITA, so that, in only three months, we were able to reach our original goals:
- A productive FrameMaker configuration for customer use was completed.
- The first complete user guide (consisting of approximately 100 pages) was created and published in this tool environment.
The customer was able to quickly install the new documentation environment and immediately start production. Since then, all their product documentation has been created in this DITA-based environment.
Organization and Workflows
As a result of the new documentation environment, the customer reorganized its documentation responsibilities and workflows.
The customer established a central department for documentation consisting of three technical writers. They are responsible for all publications, determining which content is to be published when and where, and defining and maintaining documentation standards.
Workflows and Tools
Documentation is created by several authors. Up to 30 engineers provide input. Different authoring systems are used to make sure that each group is supported.
Round-trip editing with structured FrameMaker
The technical writers in the documentation department use FrameMaker for creating and publishing documents, as illustrated in Figure 2.
Figure 2: Writing Workflow
Raw XML editing
For occasional use, FrameMaker is too complex and too expensive. The engineers use familiar developer tools such as XMLSpy and Emacs. A layout preview is provided with suitable DITA stylesheets. Some use Authentic, the free and stand-alone version of XMLSpy, and Stylevision, the stylesheet editor for Authentic.
The engineers provide DITA XML files as raw input for the documentation department. Content is compiled, standardized, and published there.
The task, including the challenge of producing the first manual in the new documentation environment within only three months, was solved successfully:
- Documentation has been successfully released in a short time with limited resources.
- Engineers easily adopted DITA; structured writing was a new experience.
The documentation environment will continue to meet the challenges of today and the future, making it easier and more cost-effective for engineers, information architects, writers, and translators to create, access, and manage their information.
Keys to successful implementation
- The tool environment could be set up early and quickly.
- The documentation department had the skills to define structures and restructure and rewrite content.
- No effort was wasted importing or converting existing sub-optimal documentation.
What do the engineers think?
“DITA really forces you to think about the content you are writing as you have to choose the elements you need to use, this makes it difficult to create blah, blah content.”
“Sometimes it is irritating to tag the content, as you would like to just write down the content that’s in your mind, just like in MS Word. With DITA, you have to check what kind of information you want to include, for instance, “is this tag allowed at this position”, and so on.”
Comet Computer GmbH
Sissi Closs is a Professor of Information and Media Technology at the Karlsruhe University of Applied Sciences. She is co-owner and Managing Director of the Munich-based companies Comet Computer GmbH and Comet Communication GmbH. She is one of Germany’s leading experts in XML and online documentation. She has been teaching DITA for more than 4 years and has successfully implemented DITA in a variety of projects to produce manuals, online help, training material, and product sheets.
Single-Source-Publishing: Topicorientierte Strukturierung und DITA
DITA auf den Coverpages
DITA Open Toolkit
DITA Consulting and Training