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:

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.

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.

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.


Do you agree?

Please share your thoughts below.

Ted Nelson on the future of text

Mike Atherton, Lead Instructor at General Assembly London, tweeted a link to a 2011interview with Ted Nelson on the future of text, document abstraction and transclusion.

Ted Nelson is one of the pioneers of information technology. He has been credited as being the first person to use the words hypertext and hypermedia (although he denies this), transclusion and virtuality.

Ted Nelson on the Future Of Text, Milde Norway, October 2011 from Frode Hegland on Vimeo.

It’s an interesting description of how content should be independent of format and media, so it can be portable, re-usable and presented in ways that best suit a reader’s needs.

Writing troubleshooting topics

It’s a fair bet that the introduction of the new Troubleshooting information type into the DITA 1.3 technical authoring standard will affect how all Technical Authors write troubleshooting topics, regardless of whether they use DITA or not. That’s because the proposed elements for troubleshooting topics make good sense, and it offers a standardised approach to writing these types of topics.

According to the Oasis DITA standards committee,

Troubleshooting topics provide descriptions of and solutions or workarounds for problem situations that users might encounter. Users refer to troubleshooting information to understand what condition or event generated their problem situation and to find out what they need to do to recover from or work around a problem, or to prevent a recurrence of the problem.

The user would see a topic that looks roughly like this:
Continue reading

Delegate review of Cherryleaf’s DITA elearning course

Craig Wright emailed us to let us know he has posted a review of our DITA elearning course (see Review – Cherryleaf DITA e-Learning Course).

His conclusion was:

The Cherryleaf DITA course ticked a lot of the boxes for me:good content, good value, and available without having to travel to the South East. The introduction to the key DITA areas was presented very well – I have read similar information in books and online, but I was able to absorb it much better through the e-learning course.

Thank you Craig!

We’ve launched our online DITA self-study elearning course today

We’ve launched our online DITA self-study elearning course on the Cherryleaf website today.

This online training course teaches the basic skills, and provides an induction, in how to create content using the DITA XML standard. The learning modules in this course contain videos of the trainer with supporting slides and images.

Here’s a sample from the first module in the course:

This video is shown in a smaller size than you’ll see in the course. To maximise the video, click on the fullscreen icon (which looks like a computer screen) on the video player’s task bar.

Our plan is to offer online courses covering the fundamentals of different technical communication subjects, and classroom courses covering the more advanced aspects.

For details on the DITA course, see :

Cherryleaf’s online DITA self-study elearning course

New training courses are on their way

We’ve been busy bees recently, working on some new elearning courses that we plan to be introducing soon. Shortly, we’ll be offering an online course on DITA Fundamentals, and another on Content Strategy. Both courses have been written and are at the User Acceptance and Testing stage. Of these two, you’re likely to see the DITA course released first.

There are two more online courses in the pipeline, which we hope to release at some point in 2014. One relates to policies and procedures, the other to elearning/screencasting.

Our intention is to offer basic courses online, and  advanced courses in traditional classroom format. Where there’s demand, we’ll also use Google Hangouts to deliver the advanced courses to overseas delegates.

This October: Dr. Tony Self’s DITA training courses in London

Dr Tony Self is coming to the UK at the end of October, and we’ve arranged for him to deliver two training public courses on DITA whilst he is over here:

Tony is the author of The DITA Style Guide, and he has a PhD in DITA.
The training will be held in Westminster, in sight of the Houses of Parliament. Each training course is limited to 10 delegates, so book early!