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 – Mozilla Developer Network

Mozilla is an organisation that always seems to be doing innovative things with their documentation. One of the experimental functions it has introduced to its Kuma wiki platform for the Mozilla Developer Network (MDN) documentation is an experimental PUT API that makes it possible to create and update articles remotely.

Mozilla suggests a number of ways it can be used:

You can create a page for your project and update content in certain sections from automated build, testing, and deployment scripts. This can help you keep your community up to date with your project’s progress.

If your project offers documentation alongside source code, you can push HTML renderings into a subsection of MDN. This lets you maintain docs in a way that’s appropriate for your team’s workflow, while still contributing to MDN and allowing localizers to translate the content.

Fro example, Mozilla’s programmers are able to write scripts that automatically generate articles based on contents of header files they’re creating. The API uses HTTP, which means software engineers (and other writers) effectively have the freedom to use the application environment and libraries of their own choice.

Kuma itself is an open source platform written by Mozilla in Python, using the Django framework. Contributors can fork the Kuma repository on Github, make changes to the content, and push the revised content back to the wiki.

It will be interesting to see if this succeeds, and if this type of platform extends further out than its use for developer documentation.

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

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

The secret to user generated and crowd sourced content

Mozilla’s Janet Swisher had a number of useful tips at Technical Communications UK 2012 on how to encourage user generated and community based content:

  • People contribute because they want to learn something and for personal growth. You need to recognise this work.
  • Crowds aren’t smart, communities of peers are.
  • Create a community about the topic of interest, not solely about your product. For example, create a community on camping, not on your brand or your camping products. Solve common problems, rather than niche ones.
  • Community based content is where contributors share a common goal. User generated content is often “all about me”.
  • You can review contributions before they go live on the site, or review them after they have been published. You need to choose the approach that works for you.

Having a forum where customers can express their views can be deeply uncomfortable for organisations. Organisations tend to encourage what Leon Benjamin called a “red zone/green zone mentality”. The green zone is safe and trustworthy and within the organisation. The “red zone” is anything outside of the organisation – and can be seen as risky, dangerous and untrustworthy. Yet the reality is that most people get information from outside the organisation (from the red zone).

Users will express opinions and publish contributions on other sites, if you don’t create your own forum. If you create the community, then you will be more able to control the accuracy, authority and accessibility of and to this information.

Having said that, sometimes you need to publish to areas outside of your control. For example, issuing your manuals via Amazon Kindle might expose you to user reviews. They could say they hate it or that they love it. That public feedback can be daunting, but remember we all have our filters to assess the information.


Education technology – Is this also the future for Technical Authors?

(Click on the image to enlarge)

Edudemic has created an infographic outlining the likely future for education. Other education sites, such as, suggest the future of study will have three main strands:

  • spend some time with experts
  • spend time on your own, and
  • spend time with your peers

If education follow this path, will this be true also for technical documentation and other forms of User Assistance? How will Technical Author adapt to these trends?

Review of “WIKI: Grow your own for fun and profit”

XML Press kindly sent me a reviewer’s copy of Alan J. Porter’s book “WIKI: Grow your own for fun and profit”. I interviewed Alan earlier in the year (which you can see on the Cherryleaf YouTube Channel), so it was good to see the book that he was mentioning in the interview.

It’s important not to think that wikis only = Wikipedia. You could argue that applications such as Confluence and Mindtouch 2010 are wikis as well – wikis enhanced with powerful tools for software user documentation, but wikis, nonetheless.

As Scott Abel says in the introduction, most organisations have yet to manage the art of managing content. They make two common mistakes: (1) they see content as either documents or structured data, and (2) they see it as purely a software problem.

Wikis offer technical communicators a handy route into an organisations for them to tackle poor content. That’s because wiki software is generally very cheap and the techies like them. There are still issues around “round tripping” (getting content in and out, and back in again) and link management, but these are not insurmountable.

Alan, I’m pleased to say, has not been seduced by the software, but has set the use of a wiki within a very usable framework. He’s spot on when it comes to the benefits a wiki can offer and the implementation approach to take.