JoAnn Hackos, Comtech Services, Inc.
Reprinted from Information Managment News, September 2012

Joe Pairman, information architect and general factotum at HTC, and I have been having a running discussion of the benefits of minimalism. When I recommend that groups begin their DITA implementation with minimalism training, it is to reinforce or learn about the ways that written communication ought to work in delivering content to consumers.

Certainly, just because the DITA over-arching model allows something, the information model that a group chooses to support and implement should consider a much more constrained approach.

For example, because DITA allows five levels of bulleted list that does not mean that a content consumer will be able to follow such a descent into an obtuse subordination logic.

Each organization has an obligation to reinforce sound technical communication or similar principles by constraining their models. Groups that foster a “free-for-all” by telling writers to use their DITA tools any way they like are actually fostering chaos. I’ve seen many groups that have had to recover from an initially unplanned approach. It becomes painful, time-consuming, and costly.

Joe mentions that aside from the benefits to the user, good information design can sometimes save us from complicated processing tweaks (which may not necessarily make things easier for authors in the long run). And, Joe’s team of writers has found it incredibly helpful to learn about minimalism and build a consistent model that supports their users’ goals.

He points out that he has always tried to make the HTC technical implementation support the information model, not the other way around. They now use constrained DTDs to limit the available elements to those in the Information Model that everyone has agreed to use. And they’ve set up their templates to promote certain norms, for example, removing XMetaL’s auto-added <stepresult> from the step mini-template. Their policy is to only use <stepresult> where it’s really helpful, not just to tell users what they can see on the screen already.

What Joe finds, like many other groups we work with, is that information architecture is an ongoing process. They have made some important interim tweaks to their authoring guidelines based on user feedback and analytics data. They have figured out how to improve the authoring experience, and they have implemented additional technical output requirements.

As HTC has added new products, the information developers have had to evolve their information architecture. They return over again to their content to thoroughly re-evaluate their decisions based on the principles of minimalism. It’s surprising how much they have been able to improve the second time around.

Joe and I would love to hear other people’s experiences in the ongoing process of refining the information model and authoring guidelines. Please let us know what you are finding as you experience your second, third, or sixth year of your DITA implementation.

Feedback from Hendrik Achenbach:

Hello JoAnn,

Hope this finds you well. I enjoyed your article in the most recent Information Management newsletter and wanted to share some feedback.

I certainly agree that it does not make a lot of sense to let content creators use the full range of what DITA allows. However, I’ve been thinking about the topic of restricting writers by using a specialized DTD or schema. I think that’s what they do at HTC, according to the article, and we at SAP are following a similar approach in our new, DITA-based infrastructure for educational content.

One of the advantages of using a standard such as DITA is that you can exchange content with others, for example, by importing content created by a business partner into your CMS. Now if your business partner either uses an unrestricted DITA schema or implements a different kind of restriction, importing the partner content into your CMS might lead to problems. While it is obvious that restricted or specialized schemas can be shared in an ongoing partnership, the overall approach might still lead to restrictions in reusing content.

The alternative I see is introducing restrictions on elements that can be used through the editing environment by not exposing the full set of elements to the user (example: Editor stylesheets in Arbortext editor). Such measures do not fully guarantee that only a restricted set of elements is used because “clever” users might find a way to edit the content in a different editor, but I would assume that this risk can be mitigated by introducing strict operational guidelines.

This approach could help to ensure that content can always be shared and reused across organizational boundaries.

With kind regards,

JoAnn’s response:

Hello Hendrik,

In fact, I do agree with your position, especially when you are getting started. In my Introduction to DITA book, I first recommend hiding elements in the XML editor as the first step to take to control authoring. However, many organizations should also create a shell model that completely eliminates some aspects of the DITA domains from the start. For example, if someone is creating content for end-users, they may never need the programming domain and can remove the entire domain from their shell model. The same might be true for documentation teams that are not using the machine industry specialization. That can also be removed as a whole.

So if we order the steps:

1. Hide elements you don’t want writers to use from the XML editor’s display
2. Build your shell model, leaving out areas of the DITA DTDs that are not part of your content (you can always restore them)
3. Create constraints
4. Create specializations