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:
- Appending content to the bottom of a page
- 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:
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.
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:
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.