4 steps for a successful content migration project

Migrating your technical content to a new authoring tool is a great opportunity to not only modernise your documentation workflow, but to also get a bird’s-eye view of your entire information pool, allowing you to tidy up the project by identifying opportunities for content reuse, removing unused content, and designing information in a way that is easier to maintain in the future.

One of the main advantages of migrating all your content into a new, purpose-built authoring tool is content centralisation. By consolidating current, and any future documentation and resources into a single, unified platform, you can:

• Streamline your information management and authoring output.
• Improve accessibility.
• Ensure consistency across your product and documentation range.
• Enhance content reuse capabilities.
• Simplify content maintenance.
• Streamline collaborative authoring.
• Optimise content for quicker, easier, and cheaper localization.

Post-migration, all the above improvements will have the added benefit of, either directly or indirectly, enhancing customer experience and satisfaction with your product or service. However, without proper planning and a robust project outline, content migration can quickly become unmanageable.

Here at 3di, we’ve migrated thousands of pages worth of documentation and have created and fine-tuned a content migration process that we regularly use on customer projects. Outlined in the steps below is a high-level overview of the migration workflow that you can use for your own migration projects:

1. Analysing your current documentation and overall migration requirements
2. Designing the implementation and ensuring quality
3. Migrating the content
4. Reviewing the content after migration

This blog explores the above stages in detail, and why you should follow them, using MadCap Flare, our authoring tool of choice.

Analysing your current documentation and overall migration requirements

Like any authoring task, the analysis stage underpins the entire migration process; it acts as a way to lay out your requirements and analyse the content you want to migrate. You may want to ask yourself the following questions:

• What kind of output is required? For example, digital PDF, printed document, HTML, or a combination?
• Is there any complex content in the source documentation that the team will need to investigate to be able to implement? For example, embedded videos.
• What kind of styles are used in the source authoring tool, and can they be easily replicated?
• What is the purpose of the migration? For example, is it due to a company rebranding campaign or is it a modernisation project? The reasoning will affect the design stage onwards. The former, for example, might require a style guide that differs drastically from the current documentation.
• Will the project involve only content migration, or will it be a combined migration/content update effort? This will depend heavily on the quality of the content and time considerations. If you’re looking to make updates, we recommend doing so after the migration, as this will allow you to fully leverage the functionality of the new authoring tool.
• Will you be using a source control software, such as Git? If so, you need to think about what kind of workflow will best fit the project and if you or your team need any additional training.

You need foundations to build a house, without them the project can’t begin!

Designing the implementation and ensuring quality

The design stage principally involves setting up the new authoring tool so that it adheres to the requirements outlined during analysis, and creating guidelines for authors working on the project to ensure consistency throughout, including setting up source control and creating guidelines for its use, if this is something that you want to utilise.

In the case of Flare, tool setup involves setting up templates, creating output targets, TOCs, and topics, and designing and implementing the documentation set’s visual style. For more information on working in Flare, read our blog posts about Flare content management and Flare tips & tricks.

Having a robust set of guidelines is a must for migration projects. The guidelines function as an internal wiki for everyone on the project, which help ensure content is migrated in a consistent way, regardless of the number of authors who are involved, and save time during the post-migration review. Each project is different, and you should tailor these guidelines to the requirements and idiosyncrasies of each. Guidelines should include general considerations, a procedure describing the migration process, and guidance on migrating specific content types, for example:

• Lists
• Graphics
• UI strings
• Tables
• Safety notices
• Cross references

Flare uses CSS stylesheets to control the appearance and structure of style elements; this means that, during the migration, each content type requires careful attention to ensure that the correct styles are consistently applied. You can apply styles either manually (by selecting them from the Style drop down or from the Style Window), or by using Flare’s native import feature, which allows you to map the source tool’s styles to those present in Flare, and even modify them as required. When migrating manually, some content types require a little extra work; for example, you cannot just copy and paste images as you would in another authoring tool, they must first be saved as files within the project folder structure and then inserted.

To ensure a high-quality migration project at all stages, incorporate a quality assurance framework as part of the design stage. Before beginning any migration tasks, you must ensure that all authors working on the project are up to speed on the project requirements, migration guidelines, and any deadlines. This is best achieved by having a preliminary onboarding phase, ideally a few weeks before the project is set to begin, to allow for everyone to be caught up and the guidelines fine-tuned if required.

Migrating the content

Once all the preliminary groundwork has been laid, you can begin migrating. There are two different ways to do this, either using Flare’s native import feature, or doing it manually. Here at 3di, especially for complex technical manuals and larger documentation projects, the copy and paste approach, alongside some proprietary in-house automation, is our preferred option to ensure a smooth and consistent migration. It also has the added benefit of working as a self-review, allowing you to spot a variety of issues within the text at a sentence, paragraph, and section level, concurrently with the migration.

Depending on the chapter length and size of the documentation, split the migration into manageable tasks – several chapters per task if they are short, or one chapter per task if the chapter is particularly long – before assigning to your authors. This approach allows the authors to focus on smaller, specific content areas, improving quality and accuracy, while also making it easier to monitor the overall progress of the project. Breaking down the work also enables quicker review cycles, minimises the risk of rework, and balances workloads more effectively across the team.

When it comes to migrating the content manually, what exactly is the best approach to take? This all depends on how thorough you’ve been with creating the migration guidelines, time considerations, and the complexity and quality of the source documentation.

On the one hand, it might suit you to get all the content copied over into Flare first, without applying any styles. This exposes your authors to all the different types of content present in the source documentation – after which, decisions can be made about how and where to apply styles. This approach may be advantageous in the case of a multi-document migration project; you can use the first document as a guinea pig of sorts, to get a feel for the type of content present, and then, for the remaining source documents, as long as they follow the same style conventions, you may find it more beneficial to use the approach discussed below.

On the other hand, if you’ve done a robust analysis and created accurate migration guidelines, migrating and applying styles at the same time is another option. But should you copy and paste entire pages at a time, or on a paragraph-by-paragraph basis? The migration granularity that you choose depends on a couple of factors; is there a time pressure? Is there a lot of non-textual content (for example, tables and images) and special formatting? Maybe inline styling is prevalent throughout? After considering all such circumstances, you can make a decision. If there’s a lot of non-textual content, copy and paste paragraph-by-paragraph, and apply styles as you go – it can be quite easy to forget them otherwise! If there’s a time pressure and/or the majority of the content is textual, migrating the content and applying styles on a page-by-page basis is our preferred approach.

Reviewing the content after migration

After you’ve migrated the content, it should be reviewed for accuracy – ensuring that there are no discrepancies, formatting issues, or content omissions – and the output checked to make sure that it adheres to all requirements as set out during analysis. To achieve this, you can divide the review into the following three steps:

1. Peer review
2. AI-powered proofreading
3. Final checks

A peer review done by a fellow team member is, and always will be, an invaluable and necessary step of the review process. The peer reviewer should focus on comparing the migrated content with the source content, making sure that all the content has been migrated as expected, that the author has followed the migration guidelines, and that all styles have been applied and formatting is correct.

With the massive leap in AI functionality over the past few years, various use cases have presented themselves for Technical Authors, one of them being proofreading. You can utilise the likes of ChatGPT and Microsoft Copilot to proofread the migrated content and look for spelling and grammar mistakes that might have been missed during peer review, as well as guidance on improvements, if this is covered by the scope of your migration project.

The final stage of the review process involves building the output for the migrated content and making sure that the high-level elements of the documentation are functioning as expected. This includes checking the layout of the TOC, pagination and page numbering, chapter numbering, header and footer text, cover and back pages, and the overall documentation look and feel. Additionally, in its build process, Flare includes verification checks and a build log that shows any warnings or errors that need your attention.

Next steps

You’ve completed the migration, and all content has been reviewed and approved – what now? If this was a one-off migration, job done, give yourself a massive pat on the back! If this was part of a modernisation initiative or similar, now is the perfect time to come up with an improvement roadmap, updating your documentation based on issues found during migration, implementing any nice-to-haves that you’ve been eyeing for a while, and finding opportunities for content reuse – you may even find that you now have a greater understanding of the overall content flow and can use that new-found knowledge as an opportunity to restructure the layout of your content.

Migrating your content can seem daunting at first, but a well-planned and executed content migration project can significantly enhance your documentation process, making it more efficient, consistent, and user-friendly. By following the steps outlined in this blog, you can ensure a smooth migration, while still maintaining the quality and integrity of your content. It’s also an excellent opportunity to refine and update your overall documentation strategy to ultimately deliver a better experience for you and your customers. For more information on the services 3di provide and how we can help you to migrate your content, contact us.