Migrating documentation

There are many challenges technical writers might face, and an out-of-date toolchain can make technical writing a chore. This is where migration comes in!

In this post, I will introduce why someone might consider migrating their documentation from one tool to another, the necessary steps to consider, and some common pitfalls.

Why migrate in the first place?

Migrating from one documentation tool to another is like moving to a new city. The sheer ordeal can make you wonder: Is this even worth it? I'm currently experiencing this very example in my actual life, so I decided to write about migration. I can assure you that even if the task seems unsurmountable, it can create a new environment, be that documentation-related or in real life, it can lead to a better life.

Limitations of your current tool

Think of your current tool as your old neighborhood. It was good for a time, but perhaps:

• The local store (UI) became outdated.
• Public transport (search functionality) often breaks down.
• High rent (costs) for not-so-great amenities (features).
• Awkward location of the neighborhood (collaboration difficulties).

Important points to consider in a new tool

If you are thinking about switching to a new tool, you should consider the following:

• Cost (both for the migration effort and for the tool itself)
• Features
• UI/UX
• Collaboration options
• Ease of integration with existing tools
• Customer expectations

Each of these points could warrant a lengthy conversation in itself, so make sure you think all points through. Migrating your documentation is no small feat. Even for smaller documentation, it can take anywhere from 500-5000 (for some larger ones up to 50000!!!) hours of work easily. This is why I cannot stress it enough: it's crucial to ask questions from your stakeholders, be that your manager, your customer, or your technical writer teammates.

Ask questions like:

• What are the business-critical features?
• What are the most significant customer complaints the new tool should remedy?
• How much time and cost will we save with the new tool?
• What tools will we have to integrate?

These are just a couple of examples; your business might be looking for something else entirely, but they can serve as starting points.

Reluctance to change

Your technical writer colleagues, even the people who have been the most vocal complaining about the old tool, might not like the idea of moving to a completely new one. Realize that this is completely normal. People get emotionally invested in something they use every day. They understand it, they know the shortcomings, and they have learned to live with it. Just like with any change, you have to involve each team member differently.

Seniors

Perhaps this is the most important factor in the initial stages of documentation migration. Getting the Seniors on board. If you are the information architect or the technical writer leading the migration efforts, it's paramount to work with the other senior technical writer colleagues.

This can be your greatest crutch during the entire effort. Chances are, if you are leading the migration, you are a senior yourself, but getting different perspectives from other senior colleagues might shed light on important factors you might overlook. You should work as a team on such a big project, and involving everyone in the kick-off stage can be a great way to establish roles. Find out who has enough time on their hand to take on bigger tasks.

Your job is to involve the senior colleagues in demos, listen to their feedback, and be as transparent as possible.

Mediors

Mediors (neither junior nor seniors) usually take up the bulk of your team (although that may vary from company to company). They are usually the people who take care of most documentation updates, so they may provide essential insights during the testing phases. This is especially true if you are considering a phased rollout, where only a handful of team members would test a new tool out first. In those cases, you could get most of the necessary feedback from your medior colleagues.

Juniors

Junior colleagues can provide a surprising amount of feedback. They may take to the new tool easier than medior colleagues, as they might not have had the time to fully get used to the weird limitations of the old tool yet. It's extremely important to provide ample opportunities for learning in the form of training, QAs, and feedback sessions.

Migration steps

Now for the nitty-gritty part. When reading these points, you should already have a clear picture of what features the new tool should have and who should be involved in the migration process:

1. Determine scope: What part of the documentation will be impacted? Will it be everything or just some parts?
2. Create a sandbox environment in the new toolchain: Test the features. Ensure that everything is working as it should.
3. Determine if you can automate any part of the migration process: For example, if your documents are in XML, you can easily transform them into Markdown using a script.
4. Start creating the production environment: Migrate a small part of the existing documentation and, again, double-check if everything works as it should.
5. Migrate the rest of the documentation.
6. Structure documentation: You can make it have the same or a different structure as it.
7. Create a test build and ensure that the existing documentation looks as it should. (This might be the longest step, depending on the script quality and the tool interoperability. Here, you will be able to measure your preparedness).
8. Ensure that links, images, and other media work correctly.
9. Place logos, create landing pages, etc.
10. Integrate auxiliary tools and ensure that they are working properly.
11. Communicate with all stakeholders and prepare for launch.
12. Go online!
13. Don't forget to get rid of old documentation if applicable.

Those should be the steps in broad strokes. As you can probably imagine, each of these steps could take a considerable amount of time, so I cannot stress enough how important it is to prepare as much as possible.

Hope this short guide has given you some insight. If you have any questions, you can reach out to me on the discord channel.