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.

Reflections on the TCUK15 conference

I was one of the presenters at last week’s Technical Communication UK 2015 (TCUK) conference. TCUK is the Institute of Scientific and Technical Communicators’ (ISTC’s) annual conference for everyone involved in writing, editing, illustrating, delivering and publishing technical information. It’s an opportunity for Technical Communicators from the UK and mainland Europe to meet up and mingle, learn and present.

auditorium at tcuk 15 conference

Here are my reflections on the event.

Continue reading

Ellis will be speaking at MadWorld 2016

MadWorld conference

Cherryleaf’s Ellis Pratt will be speaking again at MadCap Software’s conference on technical communication and content strategy conference. MadWorld 2016 will be held between the 10th and 12th April 2016 at the Hilton San Diego Resort and Spa, in San Diego, California.

Continue reading

Presentations at Technical Communication UK Conference, Autumn 2015

Cherryleaf’s Ellis Pratt will be speaking at Technical Communication UK 2015, which will be held between 29th September and 1st October 2015, in Glasgow. Ellis will be speaking twice, about:

  • Creating an academic course in technical communication, and
  • Help in the User Interface – a case study in first user interaction and embedded Help formats.

If you’re planning to attend the conference, we look forward to see you there.

Customers as advocates

I attended the Customers as Advocates conference yesterday, at the invitation of the hosts Strand Writing and Design. Strand is a copywriting company, and their conference focused on the challenges of creating relationships with customers that will lead onto them providing customer references and case studies.

Although the conference was focused on case studies and advocacy, I was struck by the implications for the user assistance and technical content that organisations produce.

Below are my summaries of two of the presentations.

Ian Williams – Customer Experience and the disappearing sales process

Ian Williams, of Jericho Consulting, looked at what he called “the disappearing sales process”. He quoted research from Google, IDG and Forrester showing how important content and customer recommendations are in the buying process today:

  • 57-70% of the buying journey is complete before a potential customer looks at marketing content or engages with anyone in the sales team (source: CEB/Google).
  • 21% of buying cycle is spent by business buyers in conversations with peers and colleagues (source: IDG).
  • 56% of the buying cycles is spent by business buyers searching for and engaging with content (source: IDG).

He also stated that Customer Experience, and an organisation’s brand, is about “keeping your promise” – that the customer’s expectations must be matched by what they actually get.

Implications for technical communication

This is more evidence that the content Technical Authors create (user guides, FAQs, Help, getting started guides, troubleshooting information etc.) can be an important factor in the buying process. Prospects will do their research, and they seek out trustworthy content about a product.

It also highlights the importance of a consistent message and experience throughout the customer journey. The “promise” must be consistent in the marketing and the user assistance. You also need to deliver on that promise; poor quality post-sales content just won’t do any more.

Mark Gallagher – How Formula 1 will affect your business

Mark Gallagher has been a senior F1 executive of over 20 years. He talked about how the business of Formula 1 is changing, and how those developments are likely to affect the wider business world.

He explained that the Formula 1 constructors were now the world’s experts in capturing data, analysing data, and providing information on performance improvement to the end user. Constructors, such as McLaren, were now applying this expertise to a wide range of industry sectors.

Mark predicted that this expertise could be applied to the “Internet of Things”, where devices capture data and provide advice and information to the end user.


If these capabilities were applied to mainstream software, perhaps we could see applications such as Word and Excel capturing data on how you use the software, and then providing advice on how you could have completed that task in a better way.

In fact, some applications are providing this type of feedback already. Here’s a screenshot from an Android app called Steno Keyboard. It analyses your keystrokes and tells you if there was a better way:

Screen from Steno Keyboard app

The type of development would change user documentation into performance support, and move more of the user content into the application itself.


This post represents just a few notes from the conference. It’s clear that content, in all its forms, is becoming a key factor in the buying cycle. User Assistance is not just for customers, it’s for prospective customers as well.

“Bad information is Marketing’s fault problem. Good information is Tech Comms’ specialty. Let’s do the maths.”

inbound marketing and technical communicationsThe quotation in the title is from Roger Hart’s presentation at last week’s TCUK14 conference. Roger is a product marketing manager who spent a few years as a Technical Author. In his presentation, Collateral damage: do marketing and tech comms have to fight when users get informed?, he explained some of the most powerful marketing content today is high quality user information – especially the content that Technical Authors produce.

Continue reading

Microsoft moves away from “robot speak” in its user documentation

DSC00498One of the highlights from the Technical Communications UK 2014 conference was the keynote presentation from Microsoft’s Doug Kim. Doug is Senior Managing Editor for, and leads guidelines and best practices for Voice in Office. By Voice, he means the tone of voice and style of English used in the User Interface and user documentation.

Doug Kim at TCUK14

The change in voice is something we explore on our advanced technical writing techniques course, so I was interested to see how Microsoft was addressing this topic. The good news for us is that Microsoft’s approach is consistent with what we advocate on the course (however, we will need to update the course before the next one in December to include some of the topics Doug discussed).

Continue reading

Our process for creating elearning videos

I will be talking at the Technical Communications UK 2014 conference (TCUK14) next month about creating videos for technical communication and elearning videos.

elearning video screen captureIt covers how to embed video in a course. The delegates see, in each recorded module, a video of the trainer on the right of the screen, with the slides, application walkthroughs or images on the left of the screen.

This format is more engaging for delegates than a disembodied voice talking over a slide or image.

Continue reading