So you've decided to convert your docs

So you've decided to convert your docs


So you’ve done the work and you are ready to convert your docs from one tool to another.

I, too, have done this. Actually, I am on my third time through doing such a massive undertaking. This time, as a lone writer having to maintain docs in both the old platform and the new.

It’s an undertaking.

Here’s some advice from a conversion veteran.

  • Set aside time each day to do something with your conversion project.
    You can eat an entire elephant one bite at a time. No matter how small, each step in your conversion is a step forward. Do something to take you forward every day.
  • It’s a marathon, not a sprint.
    There are no shortcuts. There will be unexpected surprises that cause delays. It will seem like the project will never end. These are all true. But you will get there.
  • You’ll do things wrong when you start. Learn and recover and move on.
    A few weeks or months down the line you’ll just have to moan when you stumble upon something you did before you knew the better way to do it. Fix it, groan, and appreciate your ability to learn and grow.
  • Management needs to understand that it’s a big project, and to set expectations appropriately for both the delivery of the converted docs and any other work they want/expect in the meantime.
    It turns out that you cannot do more than you can do. If you were doing everything you could before you started conversion, then something has to give so you can convert. Make reasonable suggestions and come up with an agreed plan.
  • Once you decide to convert and what you’re converting to, just start on it. There’s only one way to learn, and that’s by doing.
    There’s no better way to get something done than by starting to do it.
  • Find a support community that’s knowledgeable in your new tool(s) and make use of them. Slack communities, blogs, social media networks - there’s lots of valuable places where other people can help you when you come across a problem or headache. And you will.

One bite at a time, one CSS entry at a time, one paragraph at a time, some days just one period at a time, you will get there. I promise.

And, in the end, you can celebrate your great achievement.