DITA @ Cengage

By: Rich P., Sr Systems Analyst

Whenever DITA (Darwin Information Typing Architecture) comes to mind, I think back to the year that Steve Jobs introduced the iPhone. In 2007, I attended the 3rd annual DITA North America Conference and learned how this open standard can be used to assemble component content.

When I heard that DITA was being used at Cengage, I was curious to learn more and met with Shane T., manager of technical communications.

In the direction of DITA

It was most appropriate that our conversation started at IBM where DITA was originally developed. At IBM, Shane was thrown into the deep end.

I loved DITA and took to it — the clear semantic structure, its flexibility to reuse content. Not having to rewrite hundreds of topics. No one should have to copy and paste.

His thoughts reminded me of my affinity to DITA: chunking content into information types, focusing on achieving some goal through minimalism, and authoring topics that could stand alone so that they can be reused in multiple deliverables.

When Shane joined WebAssign, a learning platform that provides instructional tools for mathematics, chemistry, physics and other hard disciplines, the team ultimately moved their documentation set to DITA with the aim of obtaining reliable builds and logging.

It represented a quantum leap forward.

The transition to DITA continued after Cengage acquired WebAssign. Cengage liked what Shane and his team had accomplished although DITA remained in the background.

Challenges for writers

The story diverged for writers where DITA was very much in the foreground.

Writers were used to spending six or more months to develop long, linear documentation sets. Conversely, they were unfamiliar with rapidly building modular topics. Each topic had to make sense on its own so that it could be reused in another context.

Topic reuse requires a separation of the content from the context in which those topics are assembled. Additionally, structured content in DITA also serves to separate the content from its presentation, that is, DITA topics represent structure without form. Presentation is added through transformations before content is consumed on the application.

Writing for reuse requires planning.

We need to plan reuse well. To think about what is common in the architecture. To consider how it will be maintained. We need to examine the impact of making any change in order to prevent unintended consequences.

Aside from moving to topic-based authoring and structured writing for reuse, there are a number of other change management considerations. This kind of writing might feel constraining to some, while others could feel overwhelmed in managing an increased volume of topic files. And then there is the question of how this fits in the review and approval process.

In some instances, writers simply do not want to change.

A way forward

Shane recognized how DITA not only provided efficiencies associated with reuse, but also how well it is aligned with the user experience.

We focus on what the user is trying to accomplish, not documenting the user interface. Users read what they need when they need it. They do not read guides from beginning to end. Also, the semantic nature makes it more predictable. For example, a task topic would always be structured with prerequisites, context, steps, next actions, and related links.

Knowing that version control was needed, he piloted Git as a source repo even before developers started to move in this direction. Git for DITA provided two primary submodules, i.e., build: to build scripts and DITA customizations; and common: to reuse content across learning platforms (such as topics about managing your Cengage account).

Then there was the question of legacy documentation, including PDFs and Word-based documents. Think lengthy, unstructured content residing in large files. For a small team, Shane decided that all new technology documentation would use DITA and the rest would be moved over when the documentation was ready to be updated.

Coincidentally, some of the legacy documentation was also topic-based.

The docs were topic-based, using Madcap Flare, which is essentially a proprietary extension to HTML. We were able to convert those fairly quickly, but because of the lack of reuse in Flare we’re still discovering duplicated content in multiple topics.

In contrast, DITA was built with reuse in mind.

DITA in action

It was impressive to hear about a Cengage implementation in which a DITA element was leveraged to dynamically deliver embedded help within the user interface of an application. Reusing content was also illustrated but was less of the point.

The driver behind the implementation was to simplify the user experience in which instructors had to look up specific information for their LTI-based LMS integration (with Brightspace, Canvas, Moodle, etc.); then write down and use the information to set up the integration. The experience was error-prone and confusing, particularly in knowing where to use the information in the procedure.

The solution involved dynamically pulling help topics with specific information for a particular integration (e.g., Brightspace).

We customized the DITA help build to use a placeholder <data> element for section-specific information the instructor would need for the task. When displayed from the LMS Integration tab in WebAssign, the help topic substitutes the section-specific data, like a section ID or key and secret strings, for the placeholder so the instructor knows exactly what information to put in their LMS to set up the integration for their section.

The user experience was enhanced through a combination of contextual help and personalization.

Users know exactly what to do. They know it’s for them. It improves their confidence. Uncertainty is replaced with clarity — doing this will cause that to happen and result in success.

There is a willingness and desire to do more with embedded help. All that is needed is finding the right opportunities and taking advantage of them.

Tools

Shane’s team uses Oxygen XML Author/Editor for authoring and advanced features, and the DITA Open Toolkit (DITA OT) to build their output.

In addition to using out-of-the-box topic structures and maps (to assemble topics), the team has also created custom topics. For example, their custom glossary topic includes usage and example information along with the definitions. With DITA, custom topic types represent extensions of the core topic types in which common elements are inherited.

Most important, DITA Community Resources are shared and members of the community actively contribute to those resources.