DocZone | Managing Challenges on the Road to DITA

Posted by Christopher Hill on May 8, 2014 1:06:00 PM

DocZone DITALast week we attended the DITA North America conference in my home city of Seattle. It is always interesting to have the opportunity to interact with the DITA community. During a birds-of-a-feather lunch gathering I had some interesting conversation regarding the promise and perils of content re-use. Many of those in the conversation were new to DITA. As we discussed the challenges around content re-use in DITA I was reminded of the many pitfalls often encountered that often subvert the efficiencies promised by DITA.

The technical challenges of re-use

One of DITA's more attractive feature is its ability to provide a range of technical support for reusing content within or across publications. Traditional authoring and page layout tools tended to have limited support for re-use, and often the mechanisms for this support was proprietary. This is why more often than not these tools are underused in favor of copy and paste.

Re-use is baked into DITA

The DITA specification has effective, open concepts of re-use baked into the design. This means that using DITA for content authoring eliminates the technical hurdles limiting the re-use of content. It's topic-based approach encourages the creation of reusable content. Many organizations that move to DITA, then, are often surprised when after solving the technical hurdles content is still not widely re-used in their organizations.

Non-technical challenges

Many challenges to content re-use exist that are not technical. Unless these are addressed as part of a DITA project, wide re-use of content may remain an elusive vision. Here are some of the critical challenges that should at least be considered when trying to create an environment of content re-use.

Delivery assumptions

Most content delivered today is shifting from traditional print deliveries to a range of digital delivery formats. Yet when the content is authored it is often from the perspective of a single deliverable. Even though the tool may allow any section of a book to be re-used, you may find that the way the content is actually written prevents such use. Imagine a section of a technical manual that makes reference to other content contained in the manual. What happens if that content is re-used in a manual that does not contain the referenced section? And are such references required to be clearly tagged so that tools can provide assistance in managing such references when needed? Often this area of training is not well-addressed and authors continue to create content dependencies that are difficult to manage.

Authors who write content units only in the context of a deliverable will be tempted to write content that is dependent on the particular deliverable. You can't assume that they'll "figure it out" or that a tool can magically change such behaviors. You need to have a plan to train users not only on the technical use of the new tools but also the conceptual framework that DITA brings.


Another temptation is to try to simplify your DITA implementation in an attempt to address potential dissatisfaction from your users. While it sounds like an XML editor that hides details and "acts just like Word" might be much easier for users to learn, if such a tool becomes an excuse to hide the details of DITA from the content creators then you may actually impede the realization of many of DITA's benefits. One of the important foundations of DITA is in separating content from presentation. This is at the heart of its powers to support single-source publishing.

In such a scenario, the concept of a WYSIWYG editor makes little sense. XML editors that provide a word-processor-like view are really better thought of as tools that present a style of XML useful for the authors in the creation of content. As such, when you design stylesheets for your authoring tool you probably do not want them matching your print output. Doing so risks obfuscating many important structures that are not visible in a specific print output but may be important foundations for re-use and linking. Instead of trying to match the authoring tool to a specific output format, you should consider creating styles for authors that make apparent the information they need to manage in order to create re-usable content. Metadata, conditional tagging and other supporting structures should be made apparent and easily accessed. If hidden behind a context menu or in an external panel users may find their use cumbersome. Worse, unexpected behaviors not readily apparent to someone re-using the content may occur. Such surprises often result in users avoiding the re-use of content they can't readily understand.

Access to properly configured tools and training is critical if you expect your users to take advantage of DITA's support for re-use. Not everyone needs to have a full set of content analysis skills in order to use a DITA system, but they do need to know the details of how your particular business environment is configured.

Lack of content management

Many DITA projects start using the DITA open toolkit and a file system or shared folder. But problems can occur specifically around re-use in such a scenario. Shared folders rarely provide controlled access to content. Content in directories often provides no mechanism for tracking versions, controlling updates, and ensuring that two users do not try to modify the same content (or overwrite others' content). When a small DITA project is rolled out to a larger set of users these problems worsen with increased content re-use. If a team runs into these problems they quickly begin creating copies of content anyway to avoid the problem — eliminating any potential benefits of content re-use.

Content management is also needed to support the organization of content components. Content management systems often provide the ability to support metadata and search features that make locating potential content for re-use much easier. Relying on a shared folder typically means that as the number of content components increases users' ability to find re-usable components decreases. At some point, users may decide its easier to write new content rather than try to deal with these challenges.

Unless you have a very small team that is tightly coordinated content management is an important tool for maximizing your investment in DITA.

Earning your wings

These examples represent just a few of the many potential challenges that can surprise newcomers to DITA. Some may be addressed through training. Some may improve with experience. But it is very hard for organizations new to DITA to make content decisions before they have sufficient experience. And there is often a chicken-and-egg scenario where the promise of DITA remains unrealized without an investment in tools to properly use it. Such investment is often risky, as it may require investment in integration, licenses and products unfamiliar to your organization.

In the last several years, however, tools like our own DocZone product are available that provide preconfigured integrated DITA tools on a hosted basis. For a monthly fee, you can license the use of DocZone's best-of-breed tools in an already integrated and configured environment. If your organization is new to DITA and/or content management such a solution can enable users to build experience on a professional platform without the cost typically associated with setting up such an environment yourself. Because you are in a proven, production-ready environment you are less susceptible to many of the problems typically encountered when setting up a new DITA environment. A hosted solution also can scale to address the requirements of small and large teams. The use of DITA also means that your content can be used with other DITA-based tools if needed.

Trying to achieve the full promise of DITA is a challenge whether you try learning in an ineffective shared-folder environment or try integrating an end-to-end DITA toolset for the first time. A hosted option like DocZone is a great alternative to taking on these challenges alone.

Topics: content management, DITA, DocZone

Comment below