Versioning of Technical Documents - the Single-Sourcing Approach

Let’s talk about versioning user manuals today. This concept has far more use cases than one might think. We will name some of the most popular ones and talk about the means ClickHelp, a cloud solution for help writing, offers to solve this! ClickHelp is based around the idea of reusing content and creating multiple versions of the same documentation project. This gives you a shortcut to faster and better help authoring right off the bat.

With content reuse, all technical texts you are creating at the moment have great potential to make your life easier tomorrow. A lot of what we are going to talk about further on is connected with single-sourcing. Let me briefly introduce this concept to you. Single-sourcing is a set of techniques that allow you to create multiple versions of the same document easily. The name speaks for itself as you are using ‘a single source’ to build different variations of your user manual. In ClickHelp you can use the following tools for single-sourcing:

• Variables. Create variables and store information in them. Variables are named values. You refer to a variable by its name in your content, while for the readers the name will be replaced with the actual value. When you change the variable’s value, it will be updated throughout the documentation.
• Content Snippets. This is a bit similar to variables in terms of mechanics. If you have some instruction or another content fragment that is repeated in multiple places, just turn this instruction into a Content Snippet element and insert this snippet everywhere. Inserting a snippet will refer to the original Content Snippet and will pull the content from there. Updating multiple help topics is done in a single place now!
• Conditional blocks. You can choose not to display bits of a topic content in some outputs or choose to display something else instead. This way, the same help topic may look differently for different audiences when you publish it.
• Conditional TOC. You have the power to make topics or TOC folders conditional too - include or exclude them based on your publishing settings!
• Output Tags rule all conditional content. They are like labels that you assign to elements inside the TOC or inside a help topic and, when publishing your documentation, you can specify which content to include or exclude by specifying Output Tags to use.

Now you have some idea of what single-sourcing is - using these techniques you can generate multiple varying outputs with ease. To get a deeper understanding, feel free to refer to this article. Let’s get down to business!

Versions of User Manuals

• User manuals for different product versions. The bread and butter of most help writers. And, if approached without the right tools, it can be quite hideous. When a new product version is released, oftentimes, not much is changed documentation-wise. Sure, you will need to add descriptions of new features, but the biggest chunk of your work will consist of fixing and updating the tiniest things in the new version. With tools like variables and content snippets, making one change will suffice - the rest of the help topics where these elements are used will update automatically. So, a new product release will be a piece of cake for your documentation team!
• Multi-language versions. A popular use case, too. Can be achieved in ClickHelp easily. You can copy your documentation project to recreate its structure for the new language version. Users will be able to switch between language versions should they need to, when the user manual is published.
• User manual versions for different output formats. With ClickHelp, you can export your docs into multiple formats, like:
  • HTML5 Web Help
  • CHM
  • PDF
  • DOCX
  • DOC
  • RTF
  • EPUB
  • ODT
  • MHT
  But what if you want a printed version? Printed versions have a lot of specifics like margins, a cover, a TOC (unlike in online docs, it should be a separate page), and, most importantly, all the digital content like videos, gifs, hyperlinks, navigation elements can’t be translated into a printed version. ClickHelp can help you with all of this. Firstly, you can use Output Tags to tell ClickHelp which content should go to the printed version and which is for the online view only. Secondly, you can use conditional formatting for printed outputs. And, thirdly, all this stuff like a cover, a TOC, paper orientation, etc. can be set up within an Export Template.

• Versions for users with different proficiency levels. Sometimes, doc teams are tasked to create user manuals for users with different skill levels. How would you go about it? Would you create those as completely separate entities? I have a better idea - you can use conditional blocks and output tags to create as many versions of the same documentation as you wish. This could work like this - you could create elementary-level help topics by hiding all the advanced stuff for this user manual version. Or, you can go the other way - write your content without too much details and include additional explanations in the form of Drop-down Text and Popup Text elements that are not visible by default. When a reader needs more details, they expand a section for more information or click a term to see details in a popup.
• Versions with access restrictions. Inside one portal, ClickHelp allows creating public user manuals, as well as those with access restrictions that will be available to Power Readers only. This can work for many use cases. For example, you can have a public version of your documentation for users and another, a private one, for internal usage that will include notes and additional materials. Or, you just don’t want some documentation version to be available to the general audience at all, like Beta version guides, or partner manuals and instructions. This can be finetuned in ClickHelp before publishing a new guide - you can select the exact user roles and specific user profiles that will be able to access a user manual.

Conclusion

Versioning is something every technical writer is faced with. At ClickHelp, we looked into all major use cases and made sure that our solution supports them, making the life of documentation writers easier. Being able to create multiple versions of the same user manual is life-changing. If you are still copy pasting content, we definitely recommend that you check out the free ClickHelp trial. It has all features included, so you will be able to try everything out for 30 days and see the benefits for yourself!

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