A multi-version manual is created for different versions of your software. The main specific of a multi-version manual is that you don’t update the previous version of your manual but you create a new one. In this post, I want to tell you about how you can create a multi-version manual and what features your HAT should provide, so you can create it easily.
How to Create Multi-version Documentation
In this section, I use ClickHelp as an example for creating a multi-version manual. So, here is how it works in ClickHelp:
- For example, you have a project called ‘My Software Documentation’, and you need to create different versions of this document.
- Click Publish, select Create a new publication to create a new version and specify the version number, for example, in the Publication namefield.
- So, you need to create a new publication for each version.
Here is an example how it may look:
As you can see, it’s easy — just three clicks and you have a new version of your user manual. This approach is also convenient since your users can open the necessary version from the version selector that is typically displayed at the top.
What Features You’ll Need
Your documentation may consist of a great number of versions and it will be challenging to reuse content among those versions, update them if it’s needed and the like. So, here is a list of features that you should pay attention to if you choose a technical writing tool for the purpose of creating multi-version documentation.
- Reusing content.
Usually, some help topics of different doc versions may be the same. And it’s not productive to just copy the whole help topic and paste it manually. The reusing content feature makes the writing multi-version documentation easier. You can learn more here how it works: Reusing Topic in Multiple ToC Nodes.
- Partial doc update.
A documentation team’s workload depends on other teams a lot, mostly on devs. There are situations when any sudden functionality may be changed before a product release. However, technical writers need to provide users with fresh information. Here is where the partial doc update feature steps in. It allows a tech writing team to publish/update necessary topics quickly and they don’t have to wait when the whole project will be finished. More info is here: Agile Technical Writing.
- Content snippets.
Sometimes tech writers need to reuse a part of a help topic. This can be content of any size — small chunks for legal notices at the end of topics, or complete instruction sets with images and external links used across locations. Again, to make this process easier and quicker, your help authoring tool should provide the content snippets feature.
- Conditional content.
When creating multi-version documentation, you may want to produce different outputs from a single source, for example, you need to create a version for beginners and a version for experienced users. Conditional blocks will work well in this situation. They may be included or excluded from the final output depending on the name of the output tag you are using. So, conditional blocks allow you to exclude certain advanced technical information from the end-user manual while including this information to the administrator manual of the same application.
- Output tags.
An output tag helps you vary the final content depending on the output type. For example, you may want to embed a video to the online version of your documentation, but remove it from the printed version of the user manual — this is possible to get this result by using a single source for both versions.
- Adjusting language for a project.
Documentation should be always user-friendly, even if you have many versions of it and it’s difficult to maintain them. That’s why it’s crucial to use a HAT that will help you. Imagine, your audience is multilingual and different versions of your documentation should be in different languages. So, what you really need is the adjusting language feature to provide all your users with the relevant content.
Ann Green, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors