How to create online Help topics that are editable by clients

In the Agile Technical Writers forum on LinkedIn, one of its members posted this question:

“I need to create an contextual online help for an complex web tool (ok, that´s not that hard). The customer must be able to add some specific job instructions to this online help by himself. The customer part must not be overridden when the online help is updated.”

LinkedIn’s forums provide limited functionality for long replies, so I thought I’d answer the question in more depth on our blog.

There are three main approaches you can take:

  1. Transclusion
  2. Appending content to the bottom of a page
  3. Embedding empty placeholder topics within topics (which the client can use to add content)

You can also simply link to an external topic. However, in this case, they wanted the user content to appear with the official content.


In the DITA authoring standard, transclusion is called content referencing (or conref for short). It enables you to insert information from one topic into another. This means you can add customised content to a topic without having to make any changes to that target topic. You specify how the information is pushed into the existing topic: Insert the information just before an element;  insert the information just after an element; or replace the information contained in an element. One of its strengths is, if you are adding new items to a list of steps, the list will renumber automatically.

Here is an illustration from our DITA training course:

conref example

The downside is writers need to be familiar with DITA, or be given a template to use.

Appending content to the bottom of a page

A common approach is to enable users to add comments and additional information at the bottom of each topic. This is the approach taken by tools such as Confluence, Mindtouch and MadCap Pulse.

madcap pulse main screen

This can work well. However, the information can be missed by it being at the bottom of the page, and if there are too many comments.

Embedding empty placeholder topics within topics

Another approach is to have empty topics within each topic. The two topics can be concatenated (joined) together to form a single topic. The client can add any client-specific content into the empty placeholder topic, so they don’t need to touch the topic containing the official content. This is sometimes called embedding topics within topics.

Here is an example of how local branch information is added to official documentation on fire safety procedures:

embedded topic example

The advantage of this approach is that it can be done with simpler authoring tools than DITA (like markdown). The disadvantage is that you may not be able to preview the final topic (to do that, you’ll need to generate the whole document), and it won’t work as well for inserting content into numbered lists.

Do you use a different method?

Please share your thoughts below.

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.