ClickHelp – Single-Sourcing Techniques

Being able to single-source technical documentation is arguably the main perk of modern technical writing tools. ClickHelp is among those help authoring tools that offer their clients various ways to single-source content.

Single sourcing means that the same documentation project can be used to create different outputs and versions. So, you won’t need to have, say, three separate project teams working on three versions of your documentation (for beginners, pros and, for example, a version in another language). This all can be done in one place now.

Single sourcing is also turning documentation maintenance into a much easier task with the help of variables and content snippets; we will also talk about this in detail further.

Output Tags

Output tags in ClickHelp are the means of managing most of conditional content. What you do is – you create a specific output tag for every documentation version you would like to have as the outcome. Like, an output tag titled ‘Pro’, for example, could be the one to help produce the pro version of your user manual, or the ‘OnlineDoc’ tag for non-printed versions.

Output tags can be either excluded from or included into the end result. For your convenience, ClickHelp has a special preview mode that allows seeing the content of a help topic with different output tags applied.
What kind of content can be conditioned in ClickHelp and managed with output tags? Keep reading to find out.

Conditional Content

This single-sourcing technique is a real time-saver. Let’s take a common use case – creating both online and printed versions of the same user manual. Instead of editing every topic, trying to make it fit into the requirements for a printed version, just make some digital content like videos visible only in the online version.

Or, as another use case example, you can place some more complex parts of your help topics in a container with the ‘pro’ output tag and exclude them from all versions but ‘pro’. As seen from the screenshot below, you can also assign multiple tags to one piece of content.

Your documentation becomes very flexible with these conditional content possibilities.

Conditional TOC

In a similar manner, you can manage the table of contents for your documentation. If you have some TOC nodes that should be present only in certain user manual versions, just assign the corresponding output tags for them, and get the desired result.

Conditional Styles and Scripts

In ClickHelp, you can make your style and script files conditional, too – yet another way to quickly obtain radically different versions of your documentation.
Each .css or .js file can be set up to have specific output settings. You can either choose these files to be published or not published with certain output tags, or just ignore the tags altogether for now.

Variables

Using variables in your documentation ensures easier maintenance in the long run. When a new user manual version is released, not every help topic gets drastically re-written. Most help topics require some minor changes (like a product version or a feature name). With variables, you won’t need to waste any time searching for these outdated words. Here’s how it works: you create a variable called, for example, ‘CompanyName’ or ‘ProductVersion’, then you assign a value to it with the actual company name and current product version.

From now on, you just need to insert the corresponding variable where needed in help topics. When the product version changes in the next release, you can simply change the variable’s value, and all your topics will be automatically updated.

Content Snippets

Quite often some paragraphs need to be repeated throughout documentation, or, there are some default steps that are used on multiple occasions. Copying these repeated snippets manually is not nearly as painful as maintaining them later – just one default step changes, and it should be fixed everywhere.
Content snippets allow reusing content easily. Just insert a snippet and, later, if something changes, fix the original snippet, and all the topics where it is used will be updated.

ClickHelp takes this functionality a step further – our help authoring tool allows merging lists, as well, and the correct numbering is generated automatically. As lists generally play an important role in technical documentation, we recommend that you check out the article on using lists correctly in user manuals. All in all, content snippets are a great way of keeping documentation up to date with a minimal effort.

Conclusion

Single-sourcing techniques can make any documentation authoring process more efficient. Just imagine how much time and effort this simple yet powerful approach can save!
ClickHelp allows creating numerous versions of one technical documentation that really differ, and adopting these techniques is not a difficult task to handle, especially, when you think about all the benefits single sourcing brings.

Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices