数据迁移方案文档_第二部分：如何成功将文档迁移到新工具

数据迁移方案文档

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.

这是第二部分：如何成功将文档迁移到新工具 。 阅读第I部分：为您的文档选择合适的工具(如果还没有的话)。

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. See slides here or watch the talk here!

注意：这也是作为“ 编写文档：波特兰2020”的演讲而提供的 。 在这里查看幻灯片或在这里观看演讲 ！

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…

作为负责在FreshBooks维护我们的客户支持团队文档的人员，我面临着以前从未处理过的事情：将文档迁移到全新的工具。 从哪里开始？ 别人如何做？ 这既令人兴奋，又令人恐惧。 这也是一个难得的机会，但是有很多人依赖我们的文档，因此期望很高。

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.

正如Yoda所说： “永远传递您所学的知识” ，因此，请从我们的迁移过程中学习，以使您的迁移尽可能成功—这是一个七个步骤的过程，可帮助您准备，预期和克服迁移过程中出现的所有问题。

1.制定项目计划 (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).

  业务案例 —包括有关为什么进行此项目的详细信息，或链接到您放在一起的演示文稿面板(您可以在第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.审核您的文档 (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

ROT —冗余，过时，琐碎

OUCH — Outdated, Unneeded, Current, Have to Write

OUCH —过时，不需要，当前需要写

YMNW — Yes, Maybe, No, Write

YMNW-是，也许，否，写

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.

空白的板块等于有机会获得干净的文档。 利用此时间来审核您拥有的所有内容，然后再移动它，以节省时间和头痛。 您的用户将感谢您为他们提供有用的文档。 不要被困在编辑遇到的每一个内容的烦琐过程中，而不会失去动力-使用目录暂时将其保持在高水平。 毕竟，您想像Kessel Run上的Millenium Falcon一样保持领先地位。

3.建立基础 (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.

  信息体系结构(IA) — IA是以有效和可持续的方式有关内容的组织，结构和标签的； 或换句话说，内容的层次结构。 查看您的目录-是否有意义，是否可以根据您将目录组织的类别和部分来查找内容？ 否则，请根据需要重新组织它。

• 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).

  卡片排序练习 -这是一个很棒的UX测试工具，您可以与一些用户一起使用(理想情况下具有各种经验)。 将目录中的每个项目写到便笺上，然后要求用户将这些便笺组织成对他们有意义的层次结构。 然后，您可以尝试根据卡片分类结果建立平均IA； IA对您的用户越有意义，他们越容易在新工具中找到文档。 ( 在这里查看我的两个用户如何组织我们的IA )。

• 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.

  搜索和标签 -使用您的IA来构建标签或标签，以为用户提供在新工具中进行搜索的快捷方式。 您还可以设置最佳做法，以标记内容，使用哪些标记以及将来何时创建新标记。

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.

坚实的基础为文档的成长留下了空间。 从一开始就计划信息体系结构意味着将来可以轻松添加或修改结构，并且您可以使用IA来帮助逐步迁移内容。 毕竟，对部队的基本了解对于成为绝地武士至关重要。

4.分块优先 (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.

通过设置IA，您可以开始考虑此迁移的时间管理。 在确定时间表时，最好不要期望它。 将您的工作分成较小的块，然后您可以基于一个块来估计时间，而不用生成随机的估计值。 您的区块越小，当出现意外时，重新安排优先级就越容易 。

时间管理技巧： (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.

  实施您的IA-使用新的IA创建这些文件夹，类别，节，面板，页面，无论此新工具用于组织您的内容如何。 随着对新工具的熟悉，您将在一片空白中获得信心，并且您将更好地了解创建新内容需要花费多少时间。 这将帮助您做出更准确的时间估计。

• 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.

  分手您的工作 -将您的IA分成几小块，并按对您有意义的顺序对其进行优先排序。 如果您是第一次组织内容，则可能需要首先确定最重要的内容的优先级。 否则，您可以先从简单的事情开始，然后将复杂的内容保存到最后，这样您就有空间犯错并尝试格式化。

• 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.让改变变得容易 (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.

  招募Beta测试人员 -Beta测试是一种有用的方法，可以让一些用户在将某些内容发布给其他人之前进行测试。 收集一些经验和资历不同的用户，让他们使用新工具并添加一些内容。 在迁移的早期阶段，获取尽可能多的反馈，以便您尽快进行路线更正。

• 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?

工具的成功取决于其用户。 您的工具只有在您的用户也同意的情况下才会成功-并且尽早使用将使他们更容易适应和采用。 您不希望您的用户像失去了国际象棋游戏的Wookie一样生气。

6.拥抱灵活性 (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”.

心态决定经验。 当您具有灵活准备的思想时，迁移似乎就不会那么吓人。 到目前为止，您已经完成的所有先前步骤将为您提供用于在天文迁移过程中处理所有事情的工具。 正如Qui-Gon Jinn所说： “您的专注决定了您的现实” 。

7.以反射结束 (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

Iceberg —表示可能会对新工具产生负面影响或使其面临风险的因素

• 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.

您是否正在考虑使用新工具，或者该工具对您来说真的很好用？ 让我们互相学习，使文档更好。

翻译自: https://medium.com/@brooke.wayne/part-ii-how-to-successfully-move-docs-to-a-new-tool-a03fac360d94

数据迁移方案文档