Do you need DITA?

Judging by Social Media last week, there were many strong opinions at the tekom tcworld conference towards the DITA authoring standard and the associated tools. It seemed, as the philosopher Swift once said, “Haters gonna hate”, and, by inference, “Hypers gonna hype”.

Eliot Kimber provided an interesting summary in a post to the DITA users group forum (Trip Report: Tekom 2015, DITA vs Walled Garden CCMS Systems):

“For background, Germany has had several SGML- and XML-based component content management system products available since the mid 90’s, of which Schema is probably the best known. These systems use their own XML models and are highly optimized for the needs of the German machinery industry…These products are widely deployed in Germany and other European countries. DITA poses a problem for these products to the degree that they are not  able to directly support DITA markup internally, for whatever reason, e.g., having been architected around a specific XML model such that supporting other models is difficult. So there is a clear and understandable tension between the vendors and happy users of these products and the adoption of DITA…
…It’s clear to me that DITA is gaining traction in Europe and, slowly, in Germany but that the DITA CCMS vendors will need to step up their game if they want to compete head-to-head against entrenched systems like Schema and Acolada. Likewise, the DITA community needs to do a better job of educating both tools vendors and potential DITA users if we expect them to be both accepting of DITA and successful in their attempts to implement and use it.”

This may have led those who are asking, do I need DITA?, to come away from the conference more confused than before. So, we thought it might be useful to provide a rough guide to whether it’s worth adopting DITA:

[ezcol_1third]

You probably don’t need DITA if:

  • The way the content looks to the user is the most important issue.
  • You have fewer than four writers.
  • You write narrative content.
  • You have limited budgets for tools, training and migration.
  • You don’t have the time to deal with the issues around changing working methods.
  • Your content has a “shelf life” of less than two years.
  • You use a lot of graphics with annotations.
  • You need to customise outputs [added] for individual documents [added] (such as PDFs).
  • The cost of migrating existing content will be expensive.
  • You want the presentation layer embedded with the content layer.
  • You don’t want to work within strict rules regarding how topics are written (where content is marked up semantically).
  • You need to put JavaScript code directly inside topics.
  • You need to use the tools used by developers or the marketing department.
  • You want a simple information architecture.
[/ezcol_1third] [ezcol_1third]

You might need DITA if:

  • You need to write to (and enforce) a standard.
  • You need to localise content into many languages.
  • You have more than four writers.
  • You want to write semantically.
  • You need a more efficient authoring, [added] reviewing [added] and publishing process.
  • You create many variations of the same document.
  • You want intelligent content that can adapt to different users and contexts.
  • You are spending too much time on formatting content.
  • You need to re-use content in different projects and different contexts, and make those topics accessible to other writing teams who might want to re-use them.
  • You need to establish a controlled vocabulary and taxonomy.
  • You want content validated for consistency.
  • You want automated publishing.
[/ezcol_1third] [ezcol_1third_end]

You probably do need DITA if:

  • You need to share content with other organisations.
  • Your content will need to last more than 30 years.
  • You want content to be stored in an open data standard, independent of any tool.
  • You don’t want to be tied into a specific authoring tool, content management system or publishing/rendering engine.
  • You need transclusion (where an element can replace itself with the content of a like element elsewhere) across a range of media.
  • You want to have a way of generalising back to a common standard.
[/ezcol_1third_end]

 

Do you agree?

Please share your thoughts below.

5 Comments

techwriterkai

Thanks, Ellis, for a valuable, constructive contribution that rises above the trenches of heated discussion to which I let myself be dragged last week. 🙂

I think if one checked all applicable items, the column with most checkmarks will be a pretty accurate indication whether or not you need DITA.

However, some items in the “don’t need DITA” can create a false impression that “all is fine, if we just don’t use DITA”.

For example, if “the way the content looks to the user is the most important issue”, more important than accuracy and up-to-dateness, then you may have another, more serious problem in the long run.

Same with “You write narrative content” which most likely means your content is hard to maintain in the long run.

Same with “The cost of migrating existing content will be expensive”. If that is true regardless of the target format of the migration, then chances are your content is so purely structured, it is hard to maintain or use outside of your current system, with or without DITA.

The middle column, it seems to me actually needs a more specific heading. I understand this as: “You need either DITA or another topic-based structured authoring environment, probably XML-based, and maybe using a CCMS.”

Cheers, Kai.

Keith Schengili-Roberts

Nicely done! Hard to disagree with the points you make, especially for people who end up with multiple check-marks in the first column.

DITA is definitely not for everybody. I would never consider writing a novel in DITA, though it is perfectly feasible to convert an existing one. 😉

There are a few things from the first column though that I think could be moved to the middle or third columns, depending.

One is: “Your content has a ‘shelf life’ of less than two years”. To my mind that’s actually a good case for wanting some level of content reuse. Maybe reversing that to say “Your content has a ‘shelf life’ or more than two years.” (Having said that I have run into situations of content reuse from material older than that).
Another is: “You need to customise outputs (such as PDFs)”. I am not sure what is meant in this case. The DITA-OT and especially professional tools like AntennaHouse or RenderX can certainly provide “customized outputs”. If you mean “individual tweaking of PDF outputs” then yes, though that would clearly be time-intensive for whoever is doing it.
Thirdly: “You use a lot of graphics with annotations”. For a larger team, especially one that needs to localize its content, this would actually turn into a strong reason for wanting to use DITA, preferably using SVG-based images whose annotations can then be easily localized.

The other one I wonder about is “You need to put JavaScript code directly inside topic”, but in most cases wouldn’t that be considered post-output formatting? Am guessing it depends on what you want to do here exactly, but it doesn’t at first glance seem to be intractable when it comes to DITA-based output formatting, but I confess I have little experience in this area.

You might also want to add something about wanting to improve the review workflow which is perhaps hinted at with “You need a more efficient authoring and publishing process” from the middle column.

The rest of the criteria in the first column makes sense to me though. A small doc team with little to no budget, little room for change management and that needs to stick with the tools the developers/marketing hands them would not appear to be the best candidate for moving to DITA. Having said that, it also sounds like documentation team that offers limited career opportunities and growth for its few writers.

Ellis Pratt

Thank you Keith.

“Your content has a ‘shelf life’ of less than two years”. Part of that relates to organisations that see documentation as almost a throw away. They may not see the long term value in it, and willing to invest in a solution with upfront costs.

“individual tweaking of PDF outputs” – that would be a fair description. Let’s say PDFs are a topic for frequent discussion in the DITA forums.

“You need to put JavaScript code directly inside topic”. Tom Johnson’s looked at this in his post http://idratherbewriting.com/2015/03/26/misconception-markdown-is-more-limiting-than-dita-jekyll-versus-dita/

>You might also want to add something about wanting to improve the review workflow which is perhaps hinted at with “You need a more efficient authoring and publishing process” from the middle column. Good suggestion.

cud

Hi Ellis…

I have to agree with Keith on the point about Javascript “with topics”. In fact, the more you need to process your content, be it with JS or some other language, the more you need semantics and structure. I find that DITA is no impediment to my processing content. In fact, I use the conref attribute to specify a specific function to run that will replace the static content of the given element. It behaves like a conref, except it refers to a process and not to a static DITA structure. When generating HTML I can run the JS (or inject a call to it). When generating PDF I use FrameMaker — I can scan the document for these conrefs and execute ExtendScript functions on those (just an extension of Javascript). So I would say, the more you want to process your content, the more you need DITA — which is the reverse of your assessment.

Otherwise, the lists look pretty good to me. 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.