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.

Stack Overflow is moving into documentation (get the popcorn)

Stack Overflow, a collaboratively edited question and answer site for programmers, has announced its plans to add documentation to the site:

“Lately we’ve been asking ourselves “what else could we do to improve developers’ lives on the internet?”. Jeff’s original announcement of Stack Overflow said this:

There’s far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We’d like to unlock all that. Let’s create something that makes it easy to participate, and put it online in a form that is trivially easy to find.

Stack Overflow has made all of that a lot better, but there’s one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better….

…We’re hoping we can improve documentation, not just move it under the domain.”

It will be fascinating to see how this project progresses – what issues they encounter, how they tackle these, and if the solutions work.

Continue reading

Content as an API – Google’s engineering documentation

Google’s Riona MacNamara presented at the Write The Docs North America conference on “Documentation, Disrupted: How Two Technical Writers Changed Google Engineering Culture“. In the video of the presentation below, Riona explains how she worked with a small team of writers and engineers to build a documentation platform in six months that is becoming a part of the standard Google engineering workflow.

Atlassian no longer lets users comment on its documentation – good or bad news?

Last week, Atlassian sent out this message on Twitter:

This was a surprise, as Atlassian has been a strong advocate for having user comments appended to user documentation. Sarah Maddox, when she was working at Atlassian, posted the reasons why the company encouraged comments on her personal blog:

Continue reading

The big questions in technical communication

David Farbey wrote a semi-existentialist post on the challenges for technical communicators yesterday. I’d like to look at the issue in a different way, by looking at the big questions in technical communication today. The answers to these questions (which may be decided by people outside of the profession) are likely to affect the future direction for technical communicators.

Continue reading

Changing times in technical communication 2 – Workflow

Science Museum/Science & Society Picture LibraryWe’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 this post, I’ll look at how we’re starting to see the workflow for creating User Assistance beginning to change.

We found many documentation teams overstretched and starting to be asked how they could create content for new products that were coming along. Some organisations have decided they can only deal with this extra workload if they rethink the workflow for how content is created.

Continue reading

Does relationship marketing mean you also need relationship content?

relationship poster Flickr image by TRF_Mr_HydeLast night I saw presentations at the Content Strategy London Meetup from Rob Hinchcliffe (a community strategist), and Sara Treewater (Content project lead for Citi Private Bank’s Web and Mobile team) in which they both mentioned relationship marketing and how it was influencing content strategy.

If your marketing and sales strategy focuses on developing a relationship with your customers and prospects, it makes sense your pre- and post- sales content (such as user documentation) sustains and builds relationships as well. Joe Gollner has called this “relationship content”. This may mean giving people an opportunity to comment, and supplement, your user documentation. In other words, moving from a monologue to a dialogue.

This can be challenging for organisations, particularly for those where there are compliance and regulatory considerations. However, there may be little choice but to do this. Rob Hinchcliffe said in his presentation that, today, content is everywhere. There are unofficial information sources where Google will direct users, if you do not provide content that’s relevant and useful.

If this relationship goes further, you can gain a significant insight into how each individual customer and prospect behaves, and start to disrupt your industry sector. We discuss this in our latest post on the STC’s Notebook blog (we’ll post a link once the post has been published).

Webinar: The changing nature of content

You’re welcome to join us on our upcoming free webinar, “The changing nature of content”, which will be held at 7pm (GMT+1) on 24th April 2013.

In recent years, technical communicators have focused on improving User Assistance through new technologies and systems, with the assumption that the nature of the content the tone of voice, the writing style ­ should remain the same. In this free webinar, sponsored and hosted by Adobe, we’ll investigate whether the tried ­and tested writing methods from past decades still make sense today. We’ll look at the reasons why some organisations are “breaking the rules” with the User Assistance they provide.

The registration details will be posted to the Adobe online events Web page in the next few days.