Blog

Let’s Help Our Colleagues Who Refuse to Work in XML

Apr 20, 2017 2:25:00 PM / by Søren Weimann

Søren Weimann


“Looks cool, but couldn’t we just stick to what we have?”

“Being able to grab a piece of content like that would be nice, but I don’t have the time to learn this new tool.”

“Yes, I’d like to be able to publish a white paper using parts of your updated documentation, but all these tags and attributes? I don’t know…”

We have all heard these complaints. 

Since DITA XML became an open standard and DITA 1.0 was released in 2005, people have been trying to spread the use of modular and structured content beyond the traditional documentation department. Some have been successful, but many have been hitting a brick wall when they present XML templates and XML tools to Marketing and Development departments.


Time and time again, I myself have presented the opportunity of sharing content, reusing topics, conrefing legal notes and filtering output for different target audiences. They all see the benefits, but more often than not, they take one step back when they see the tools, the interfaces and appearance of overwhelming complexity. Some rule it out entirely and some have a hard time finding the available resource to prioritize the change process.

Business man in front of hand drawn maze thinking how to get through.jpeg

Is this really the case all over the world of DITA XML?

Well, before I just assume that my experience has any bearing on the world in general, I tried to find out if other people are experiencing the same thing. So I conducted a survey including 80 companies. Three types of implementations answered the survey. There are those that just aim for implementing DITA XML into one department. There are those that try to include several departments, but decide to drop one or more of them from the implementation, and there are those that implement DITA XML company wide. The survey included 1/3 of each group with a slight overrepresentation of those that decided to drop one or more departments from the implementation. I tried to find out what was challenging.

The complexity of DITA XML is less of a challenge to those that implemented into one department only. This is not surprising. Ownership alone would motivate most people to take on the challenge. I wanted to know why they limited the joys of DITA to include only their own part of the organization. 42% of them indicated that complexity was part of the reason. They did so by saying that other departments want to stay in familiar tools, the change process would be too much for them, or plainly that DITA XML is too complex for them.

Whynotothers.png

There were another group of companies that tried to implement DITA XML into several departments. 70% of these implementations indicated complexity of DITA XML as part of the reason why some departments in consideration were not included in the final implementation.

reasonsfordropping.png

And finally, for those that went all the way and did company wide implementations, 89% saw complexity of DITA XML as one of the most significant challenges in the implementation.

Sigchallenges.png

DITA XML is complex. That is why DITA XML can do so much. It allows you to manage very complex sets of documentation and minimize risk and inconsistency in an ever-changing world of product development. But if the threshold for more people to benefit from all this is so high that people don’t bother trying or give up before getting there, then we may need to provide them with a stepping stone.

What if we aim for reducing complexity and then focus on just some of the most important benefits of DITA XML?

Business man looking at hand drawing solution for maze solution concept.jpeg

I’m thinking:

  • Modular content that allows reuse of topics across deliverables
  • Topic types for task-based writing
  • Ditaval filtering
  • Semantic tagging and conrefs
  • Publishing with DITA Open Toolkit

But to reduce the change process and learning curve, we allow content creators to work in familiar tools that have been adapted to achieve some of the key benefits of DITA.

On top of this, we want to allow content that is created in those familiar tools to be published in deliverables alongside DITA XML topics. And we want to make it easy to convert content to and from DITA XML. This way people who refuse to work in XML can contribute directly to modular and structured content. Maybe they can use this chance to become familiar with conrefs, tagging and topics in a familiar tool, and possibly they can use it as a stepping stone before leaping into DITA XML to get the full benefit.

This is why we propose the Open DITA manifest!

Visit DitaExchange at CMS/DITA North America in San Diego to hear more… or stay tuned for updates on this blog.

Topics: DITA , Open DITA

Søren Weimann

Written by Søren Weimann

Søren Weimann is an Implementation Manager at DitaExchange. In the past he has headed numerous structured writing and DITA implementations as a Technical Lead, Information Architect and Technical Writer working for both multinational corporations and smaller companies in IT.

Find me on: