CIDM

April 2008


DITA Success Story


CIDMIconNewsletterSissi Closs, Comet Computer GmbH

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.

The customer

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.

The product

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

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.

The solution

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.

Challenges

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.

Objective

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.

Undisturbed productivity

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.

Single sourcing

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.

The Solution

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.

Why DITA?

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.

Why FrameMaker?

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.

Closs_Figure 1

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.

Documentation Department

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.

Closs_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 Result

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.”

Next Steps

  • Choose a content management system for integrated DITA processing.
  • Fully automate the build process for final output. The overall consistency makes it possible to automate and streamline several processes, such as building and testing topics and packaging them for multiple deliverables. CIDMIconNewsletter

Closs_Sissi_bw1Sissi Closs

Comet Computer GmbH

closs@comet.de

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.

REFERENCES

Sissi Closs

Single-Source-Publishing: Topicorientierte Strukturierung und DITA

2006, München

entwickler.press

ISBN: 3-935042-98-1

IBM

< http://www.ibm.com/developerworks/xml/library/x-dita1/>

DITA auf den Coverpages

< http://xml.coverpages.org/dita.html>

DITA Open Toolkit

< http://dita-ot.sourceforge.net>

OASIS

< http://oasis-open.org/specs/index.php#ditav1.0>

DITA Consulting and Training

< http://www.comet.de>