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.

Software companies are not selling boxes anymore

Wistia’s Chris Savage has written an article on how the company focuses on articulating its company vision to differentiate itself in a competitive marketplace.

In the article, he states:

“To buy software back in the day, you’d go to the store, buy a box, and bring it home. Inside of the box would be a shiny CD, which had your new program on it.

You’d install the program on your computer, and then you’d use it for a few years. When the next version came out, maybe you’d get a discount because you bought the previous version. If it had some good upgrades, you’d consider making a purchase.

That’s all changed.

Now when you’re buying software, you’re not getting a static product. You’re buying something that’s continually evolving and changing. At Wistia, like most SaaS companies today, we deploy fixes and improvements multiple times per day.

When we buy software today, we’re not just buying into the current benefits, features, and price. Instead, we’re making a bet on the product’s future.”

Customers expect a continuing relationship with companies. They expect the product to grow, to see an ecosystem to evolve. Interwoven into this, is the support they receive. They expect high quality information when they want to explore how to get more out of the product, or troubleshoot any issues. This means User Assistance, the online Help, must become part of the initial design, and part of the user experience. It can no longer be an afterthought bolted on once the product has been developed.

Technical communication as a brand – The CEO and the technical communicator

The CEO and the technical communicator ebookSince I wrote the post on Technical communication as a brand, we’ve been working on an idea we had for promoting the profession. The end result is another story, another free graphic novel you can download, called The CEO and the technical communicator.

It’s published under a Creative Commons licence, so anyone can forward it on, as long as they don’t modify it or sell it.

There’s a lot of factual evidence about the value of technical communicators to an organisation (such as the ROI calculators on our website), so we thought we’d see if we could appeal to the heart as well as the head by using a story-based approach.

Technical communication comes in many forms, so there were some challenges in coming up with something that was representative of the whole profession. Partly to get around this, the document shows people’s reactions to the content created, rather than showing the content itself. It also uses the word “content’ as a catch-all for document, manual, book, Help file, Web page, illustration, and so on.

We’ve also developed an ISTC-branded version that the Institute for Technical Communicators could use itself to promote the profession. We’ve sent it to to the ISTC Council for their consideration and comments. The document might be modified if they ask for any changes to be made; for example, we’re wondering if there should be greater emphasis on the writing aspect of the role.

You can download the Cherryleaf version from our website. Let us know what you think, using the comments below or by email.

Technical communication as a brand

Flickr image by Ruper GanzerOne of the tea break discussions at the Congility conference I spoke at last month was over the need to improve the awareness of technical communicators and technical communication as a profession.

I suggested the profession would benefit from having (and promoting) a simple positioning statement that explains the profession as if it were a brand. This is something I believe Tekom, the German professional body, did in the early 2000s. Tekom carried out some research in Germany that suggested as many, if not more, people were carrying out a technical communication role as part of another job, and that they were not aware the profession of technical communicator existed. So they aimed some of their marketing efforts at these groups, to make them aware of the profession. They wanted to see if they could bring these people into the Tekom membership.

In fact, I think there should be two statements to improve awareness of the profession:

  1. One saying there are these people called technical communicators who could help your business.
  2. One aimed at people who are writing technical documentation, but don’t realise it is a profession, with a professional body, standards etc. that could help them do it better.

Looking at the STC and ISTC sites, there are some useful simple descriptions of the profession. I’ve used content from these two sites to come up with the following description for the first statement:

“Technical Communicators are professionals who take technical and complex information and make it clear to people who need to understand and use it.

They have skills in providing the right information to the right people, at the right time. They communicate by using technology such as Web pages, Help files or printed content.

Having clear instructions can make all the difference to users of products or staff carrying out tasks. That’s because the need for accurate and accessible content has never been greater.”

We hope to progress this idea a little bit further, and produce something that the ISTC, the professional body for UK technical communicators, and ourselves could use.

Do you think the description we’ve used could be improved? If so, please use the comment box below.

Reputation Management – Can user documentation help quash rumours?

Photo of a tiger in the streetIn the ‘Whispers’ episode of BBC Radio Four’s Digital Human programme, Aleks Krotoski explores how rumours spread both online and in the physical world.

As an example, she looked at how two people were able to spread a rumour that a tiger was running loose in London during the 2011 riots.

Aleks claims we are now in a world of misinformation. For organisations, this means they now have to pay attention to any misinformation or rumours about their products and services, an activity that is often called ‘reputation management’.

Seven minutes into the radio show, Nicholas DiFonzo of the Rochester Institute of Technology states groups believe rumours typically because there is a lack of information from official channels, they don’t trust official channels, or because their friends believe it. People use rumours to figure things out.

This means if there is a gap in information, then rumours may fill that gap. For this reason, it’s important organisations publish their Help files or equivalent on the web, so that there isn’t any uncertainty over what your product can and cannot do. If you don’t, whatever Google serves as an alternative source of information will fill in the gap.

Where people might not trust the official marketing content, they are more likely to trust the technical, instructional information. It’s seen as more ‘truthy’.

What do you think?

Please share your thoughts, using the comments box below.

Assessing the potential savings from single sourcing

One of the main benefits from single sourcing is the ability to reuse existing content. Different departments can avoid duplicating work, which means they can save time and money.

Unfortunately, it can be difficult to quantify these savings before you move to an authoring or content management system that enables you to single source. Analysing all the existing documents in a business can be overwhelming, which means often organisations only quantify the savings after the single sourcing content management system has been implemented.

There are a few software applications that can help you analyse your existing content and determine how much duplication exists. You get a sense of how much time and effort was wasted in the past, which is a pretty good indication of how much waste you’d avoid in the future.

Continue reading

Changing times in technical communication

Deepak Chopra quotation Flickr image  Celestine ChuaWe’ve been on the road in recent days and weeks, visiting different documentation teams, and we’ve found there are distinct signs of change.

In previous years, most documentation managers have effectively been saying to us their organisations weren’t really clear about the value of documentation. As the Technical Publications team usually amounts to less than 5% of the IT budget, the successful companies have, in the past, not worried about this and left the documentation team to work out for themselves what they should be doing. However, for organisations that have been watching every percent in the budget, they’ve reduced the spend on technical documentation to the bare minimum. Of course, in a recession that’s been quite a few companies.

Continue reading

The hidden cost of technical writing – localisation

I met up with a Technical Author at the Technical Communications UK 2013 conference whom I’ve been talking to on the phone over recent months. She’s been trying to convince her bosses that they should take a less chaotic approach to producing user documentation.

I’d previously suggested she look at how much it was costing them to translate their user documentation, so they could build a business case around that. She thought they were translating the user documentation into eight languages, but, at the conference, she told me that she’d discovered it was actually 24.

With that amount of localisation, there’s an opportunity for some significant savings if they could re-use content from one Help system in another.

Continue reading