Tips on Migrating to a New Documentation Tool

Migrating to a new tool is a pain for anyone. Even when a new messenger is implemented in your company, there’s still this transition period. Yes, with sending messages being the primary function of an app, you still need time to get accustomed to the new UI.

When you are a technical writer with many documentation projects on your hands migrating to a new tool sounds like a nightmare. Let’s figure out reasons for migration to a new help authoring tool in the first place. And then, talk about the steps that can make this process easier.

Analyzing Reasons for Migration

Poor efficiency is the number one reason. Not using a tool specifically developed for technical writing purposes will always lead to poor efficiency. Also, pay attention to workflow/other functionality restrictions if you are already using a HAT. Some documentation tools may be not flexible enough, so, you’ll notice how many workarounds you have to implement in your work process.

Another indicator is the number of third-party applications you have to use while creating technical documentation. Are you using separate tools to gather statistics, convert output files to the needed format? This is some serious waste of time and money right there, so migration should be considered. On a side note: as long as reasons for migration are valid, try to pick the best time to perform it – probably, sometime after a new product release, when the dust has settled.

Finding a Suitable Online Documentation Tool

The definition of a suitable tool will be, of course, different for every help writing team. But, if you think about it, there are some general trends in the industry that can help us figure out some common traits modern help authoring tools should share. We’ve recently posted an article called ‘What Every Online Documentation Tool Should be Able to Do’, and we singled out the following functionality: single-sourcing techniques, topic statuses, user/reader roles, ready-to-use documentation templates, relevant statistics. You can work on this list to adjust it to your situation and create a perfect online documentation tool formula that will be the guiding light in your search.

Analyzing Output/Input Formats

For migration to happen seamlessly, you need to make sure that the output formats of your current documentation authoring solution coincide with what the new online documentation tool offers.

This is a very important step, as a lot of time can be wasted if the export/import options don’t go well together. Still, even if you found some nice output/input combination, some content clean-up might be in order before the migration starts.

(Optional) Content Clean-Up

This point can be optional, but since this is the case for a lot of people who are migrating their technical documentation, we can’t help but mention it. In some cases, it is easier to make the necessary changes to the content in your old help authoring tool. For example, if you are using Word as your initial format, to have a TOC generated correctly when migrating to ClickHelp, you need to make sure that your outline levels are set in your Word documents. ClickHelp will use this information to create a TOC for you automatically.

Also, if you have repeating footers/headers, you might want to delete them first as such online documentation tools like ClickHelp allow you to add unified footers/headers to all topics. You can try to go through the migration process with some snippet of your original documentation first, to see what works and what doesn’t.

Migration to the New HAT

Hooray! You’ve made it to the migration! Here, a lot will depend on how thorough you were when going through the previous steps. Plus, Captain Obvious wants me to mention the size and quantity of docs to migrate count.

The migration itself is not that scary. If we take ClickHelp as an example, it supports most of the popular import formats, so, it is very likely that everything will work out smoothly. Migrating is performed with a couple of clicks and every step is intuitive and well-explained.

(Optional) Content Clean-Up After the Migration

The same formats can have different versions, and sometimes styles or other elements don’t migrate perfectly. If you did a pilot migration we mentioned in point 4 and prepared your docs beforehand, there should be only some minor inconsistencies; as a rule, styles get affected the most.

For Web Help: Link Redirection

This is the last point we are going to talk about today, and it concerns only the technical writers who are migrating Web Help to a new tool. In this case, after the migration is over, it is important not to forget to redirect all old links to the new ones.

Conclusion

It is awesome if you have found the perfect tool that meets all your requirements and you don’t have to think about content migration. But, we would also like to warn you here – not everything is what it seems. New technologies enter the tech writing scene and what seemed good and reliable just yesterday can be bad news tomorrow. Always keep looking to improve and not stagnate. It can be difficult to break down old foundations but sometimes it is quite necessary to do so.

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