Part II: How to successfully migrate docs to a new tool

This is Part II: How to successfully migrate docs to a new tool. Go read Part I: Choose the right tool for your docs if you haven’t already.

Are you struggling with the limitation of your documentation tools? Or have you been presented with an opportunity to pick a tool to start building your documentation on? Set yourself and your team up for success with lots of preparation — so that you can choose the right tool, migrate your content seamlessly and encourage adoption amongst your team easily.

Note: This was also delivered as a talk for Write the Docs: Portland 2020. Review slides here or watch the talk here!

The view on a flight to Scotland, 2019.

To recap from Part I: Choose the Right Tool for your Docs, half of my documentation vision is ensuring we have simple and fast access to accurate product information. We knew that our current tool wasn’t supporting this vision, and we identified a new tool that could.

As someone responsible for maintaining our Customer Support team’s docs at FreshBooks, I was faced with something that I had never dealt with before: migrating our docs to a brand new tool. Where to begin? How have others done it? It was exciting but also terrifying. It was also a rare opportunity to start over, but with so many people relying on our docs, expectations were high…

As Yoda says, “always pass on what you have learned”, so learn from our migration journey so that yours is as successful as possible — a seven-step process to help you prepare, anticipate and overcome anything that arises during your migration.

1. Create a project plan

Like any journey, it begins with the first step. A project plan helps you track your work, manage your time and keep your stakeholders updated.

Whether you’ve got the green light, or maybe you’ve finally put contract negotiations behind you with an active subscription for the new tool, resist the urge to dive in and start writing all the things. Take a step back and put together a project plan first. Doing so will give you an idea of how much work is required every step of the way, and hold you accountable from start to finish.

If your company has Project Managers like mine, you can always copy from one of their templates and modify it, or make your own from scratch. A good project plan for a content migration should include the following:

Project Plan Template:

• Project Description — This should include why you’re implementing this tool and the goal of your new tool, in case a new person (or stakeholder) looks at it
• Business Case — Include details on why this project is happening, or link to a presentation deck you’ve put together (you can outline the problems you’ve identified from your data in Part I).
• Stakeholders — Specify who is responsible for which part of the project; it also makes it easy for folks to reach out to the right person if they have questions.
• Priorities — Outline where you’re flexible and least flexible with scope, schedule and budget/resources/people; this is how you prioritize tasks as they come up.
• Project Schedule — Provide or link to a calendar, Gantt chart, or something that visually depict the timeline of this migration (and it’s okay if your timelines are rough estimates for now).
• Tasks — List all of your to-dos (every single one of them), and feel free to bucket them in sections or categories to make them look less overwhelming — checkboxes are optional but very satisfying to check off!
• Project Communications — Outline what kind of communications you’ll be sending out (whether it’s a meeting, an email, or even a slack message), to whom, and the frequency. This sets stakeholders’ expectations on updates from you.
• Risk Management Matrix — Specify any potential internal and external risks that could delay or derail your migration, their impact, the mitigation strategy or action you can take for each risk, and their status (mitigated, caution, critical). This is how you anticipate obstacles before they occur and how to handle them should they arise.

Use a project plan as your second brain. A good project plan has everything documented, and is always up to date as you progress through your migration. It should be the first tab you open at the beginning of your work day, and the last tab you close at the end. After all, Princess Leia didn’t just steal the Death Star plans, did she? She planned it first.

2. Audit your docs

Next, you’ll want to evaluate your docs to ensure all of your migrated content is up to date and useful.

You have an opportunity to start fresh, especially if you’ve inherited a hot mess or if you have no idea what kind of content lurks in the darkest corners of your documentation. Auditing your docs allows you to ensure your new tool is set up for success with immediately useful docs.

Auditing Tips:

• Centralize Your Knowledge — If it’s the first time you’re organizing docs, make sure you have everything in one place to audit first. Or if you’ve already centralized your knowledge, double-check you have everything.
• Catalogue Content — Catalogue all your gathered docs into an index or a table of contents so you have a birds’ eye view of everything.
• Assess — Go through your catalogue and determine what to keep, what to change and what to omit. Don’t forget to add missing content that may have never been documented too. There are lots of labelling/rubric systems out there that you can use if you need some help:

ROT — Redundant, Outdated, Trivial

OUCH — Outdated, Unneeded, Current, Have to Write

YMNW — Yes, Maybe, No, Write

A blank slate equals an opportunity for clean docs. Use this time to audit everything you have before you move it to save yourself time and headaches. Your users will thank you for giving them useful docs. Don’t lose momentum by getting stuck in the nitty gritty of editing each and every piece of content you come across — use the catalogue to keep it high level for now. After all, you want to keep powering ahead like the Millenium Falcon on the Kessel Run.

3. Build the foundation

Next, you’ll need to consider how you want your information to be organized in your new tool while you’re in the early stages of your migration. Everything is generally easy to manipulate before the content’s added in. With a catalogue setup, you can now start building your foundation by establishing the information architecture and tagging structure.

Utilizing Information Architecture:

• Information Architecture (IA) — IA is all about the organization, structure and labelling of content in an effective and sustainable way; or in other words, the hierarchy of your content. Look at your catalogue — does it make sense and is it easy to find content based on the categories and sections you’ve organized it into? Otherwise, reorganize it as you see fit.
• Card Sorting Exercise — This is a great UX testing tool that you can try with a few of your users (ideally with various levels of experience). Write out each individual item from your catalogue onto sticky notes, then ask your users to organize those sticky notes into a hierarchy that makes sense to them. You can then try to build an average IA based on the card sorting results; the more the IA makes sense to your users, the easier it will be for them to find the docs in your new tool. (See how two of my users organized our IA here).
• Search & Tags — Use your IA to build your tags or labels to provide shortcuts for your users to search with in the new tool. You can also set up best practices for how to tag content, what tags to use and when to create new tags in the future.

A strong foundation leaves room for docs to grow. Planning your Information Architecture from the beginning means it’s easy to add or modify the structure in the future, and you can use the IA to help migrate content piece by piece. After all, fundamental understanding of the Force is essential to becoming a Jedi.

4. Prioritize in blocks

With your IA set up, you can start thinking about your time management for this migration. When it comes to figuring out the timeline, it’s best to go into it with no expectations. Divide up your work into smaller blocks, then you can estimate your time based on a block instead of generating random guesstimates. The smaller your blocks are, the easier it will be to re-prioritize when surprises come up.

Time Management Tips:

• Implement your IA — Use your new IA to create those folders, categories, sections, boards, pages, whatever this new tool uses to organize your content. You’ll gain confidence while working on a blank slate as you get more familiar with the new tool, and you’ll get a better idea of how much time it takes to create new content. This will help you make more accurate time estimations.
• Break up your Work — Divide up your IA into small chunks, and prioritize it in an order that makes sense to you. If you’re organizing content for the first time, you might need to prioritize your most important content first. Otherwise, you can start with something simple and easy first, and save the complex content for last, so you have room to make mistakes and play around with formatting.
• Understand your Productivity — Ensure you and your manager are on the same page about your time to this project. If you have to balance migration work with other duties, schedule your migration work where you’ll be less likely to be interrupted, and leave room in your day for surprises, meetings, and catch-up time. Protect your migration time as much as you can.

Prioritization makes for a smooth journey. Take control of your migration project by breaking it up into blocks, and by intentionally ordering those blocks. The smaller your blocks are, the easier it is to manage your time and avoid costly interruptions. Remember, it’s a journey. The Death Star wasn’t built in a day!

5. Make change easy

Change can be scary for some people, especially if you spring it on them suddenly out of nowhere. Even though you’re migrating content, you also need to think about how to get your users onboard too. Keep your users in mind from the beginning, and introduce changes to them gradually. Your users will determine the success of the tool, so early communication and awareness is key to a successful launch!

Launch & Training Plan Tips:

• Recruit Beta Testers — Beta testing is a useful way to let a few users test something before you release it to everyone else. Gather a few users from different levels of experience and seniority and let them use the new tool with some content in it. Get as much feedback as you can in the early stages of your migration so you can course-correct as soon as possible.
• Keep your users informed — Let them know a new tool is coming and get them excited about it by highlighting some key features to drum up excitement. Present a quick slide deck at the next team meeting, and send out teaser emails. Do this often over the project schedule so it feels more gradual than sudden.
• Build a training plan — A new tool requires training — how are you going to train all of them? Who will do the training? What do you want your users to learn, what functionality needs to be covered? Answering these questions will give you a framework to build a lesson plan from.

A tool’s success depends on its users. Your tool will only be successful if your users buy in too — and doing it early on will make it easier for them to adapt and adopt. You don’t want your users to get angry like a Wookie who has lost a game of Space Chess, do you?

6. Embrace flexibility

When migrating content, it can be a rollercoaster of excitement and drudgery. The key is that you’re migrating content intentionally and at your own pace. Use your productivity to keep your motivation high. Follow your project plan, stay on track with your blocks and be ready for anything while moving content.

Stay Flexible:

• Utilize your checklists — Check things off as you complete your tasks, and use your catalogue to strike out or highlight items as you move them over to the new tool to keep track. Seeing visible progress will keep your motivation high.
• Be flexible — Be ready for anything, and quickly pivot as needed. Don’t be afraid to expand your project plan while you’re migrating content; keeping it all written down means you can focus on your block without getting overwhelmed or distracted.
• Take breaks often — Give yourself breaks every now and then. When you clear out a block, take a moment to celebrate and marvel at your progress. Feel free to share your progress with your team and stakeholders as needed.

The mindset determines the experience. Migration will seem less intimidating when you have the mindset of being flexible and prepared. All the previous steps you’ve done up until now will give you the tools to handle anything during your astronomical migration. As Qui-Gon Jinn would say, “your focus determines your reality”.

7. End with reflection

At this point, you’ve completed the migration, you’ve delivered hours of training, and your users are finally using the tool — you may have even celebrated with a launch party. But the journey isn’t over yet. Reflection and post-migration tasks will ensure you end the project with the closure it deserves, for you and your users too.

Reflect With:

• Conduct a Retro — in Agile methodology, a retrospective (retro for short) is held at the end of a sprint to discuss what worked and what didn’t. You can reflect on skills you’ve used like time management and collaboration, and analyze processes so you can apply those lessons in the future. You can use any retro activity, but my preferred one is the sailboat with some modifications:

Our retro activity using the sailboat variation.

Sailboat — Represents things, people and processes that helped accelerate the migration project

Anchor — Represents things, people and processes that slowed down the migration

Sun — Represents what made us happy during the migration

Iceberg — Represents what could negatively impact the new tool or put it at risk

• Feedback Cycle — Future-proof your new tool so that it’s always useful and relevant to your users as your product and team grows. How are your users going to pass feedback for missing or outdated content to you? How can they get support when they’re having trouble using this new tool? A feedback cycle will ensure your docs can scale over time.
• Follow up with Stakeholders — Your stakeholders will appreciate hearing back from you on how the migration went, especially if a lot of money was spent! Share a high level summary of your retro, how the feedback cycle will work, and any data you’ll be tracking to determine the success of your tool.

Rituals help end the project on a good note. Give your migration the ending it deserves, because you’ve spent a lot of time planning this migration and executing on it. Some reflection will bring you a deeper understanding of your skills. Although your migration project is just the latest chapter of your documentation story, this new tool is the beginning of a new saga.

…and now, your saga begins.

Migration is about moving your docs efficiently with minimal disruption to your users. With a successful migration, your users are better educated and more empowered to find information in your tool. Most importantly, people are finally reading your beautiful, well-written documentation!

Are you considering a new tool or is your tool working really well for you? Let’s learn from each other and make documentation better.