Shipping new software comes with a certain level of dread. Dread because you're sure you haven't caught all the bugs and because you know you'll have to support this new software.

As a small team serving millions of page views a day worldwide there's pressure to quickly ship fixes, improvements, and features to customers. There's no time for wireframing, prototyping, or beta testing. We kinda go with the flow.

And this is the approach we took with updating our Knowledge Base.

Since we didn't know 100% what it'd look like in the end we decided to ship a huge update to the way our admin app looked all at once. We hit deploy and dealt with the fallout afterwards (after some QA of course).

So it's really no surprise that we were under time pressure to get our Knowledge Base updated in a short amount of time.

Here's how we furiously updated our entire Knowledge Base in 3 days with no preparation whatsoever and why you should probably prepare better yourself.

Getting Things Organized

The first thing we found pretty early on was how much we relied on our Knowledge Base. Ironic coming from a founder who makes Knowledge Base software I know, but the tickets came flooding in.

As soon as our new UI deployed we (rightfully) started getting confused customers. We moved things around, introduced different flows, and the elements all looked different. Our Knowledge Base was not helping.

I needed a checklist of articles we'd updated and articles which were still outdated. Almost as if we'd predicted our predicament a few years ago we had a feature just for this kind of situation—Stale 🎉

I went ahead and marked every article as Stale using our Bulk Edit tools. This gave me an easy way to make sure I wouldn't miss any articles by mistake. They didn't all need updating but I knew that I'd undoubtedly miss something if I didn't check every article.

Once I was happy it was updated by having a scan through I'd hit the Stale button and mark it as fresh. Easy peasy 🍋

Making a Mental List of Things to Look Out For

Unfortunately I'm no artificial intelligence. It's super tricky to spot incorrect information when scanning through tens of articles for mere humans like you and me—let alone hundreds.

For consistency and clarity most of our Knowledge Base articles contain a few things:

• Introduction to the article. Our articles would be a little sad if we didn't introduce the article's point in a few sentences.
• Ordered lists with flows. We use ordered lists everywhere to help customers navigate our product. With an overhaul to how things are nested a load of these would need updating.
• GIFs, GIFs everywhere. To cater to visual learners we litter our articles with helpful GIFs that show the customer what we're explaining below.

This makes it a whole lot easier to write new articles from scratch. This also made it a lot easier to update them. To combat my lack of sentient brain I created a mental list of these few things to spot:

• Is the information accurate? I wasn't looking to overhaul and think critically about each one. I wanted the information to be reliable so customers could help themselves after the UI overhaul.
• Are the images and GIFs up to date? All elements inside the articles needed to be accurate. That included images and GIFs.
• Could this article be renamed? Sometimes an article sits there for a while and as time goes on the title isn't as clear as it could be. I renamed a few articles before pushing them live.

Spot the Difference(s)

The first big difference with the new app was introducing more menus. HelpDocs is complicated and hiding away the complexity means hiding away less-used actions so the user can really focus on what's in front of them.

Adding the more menu action to the existing flows would be tricky and time-consuming. To make the process quicker I created a Clip with "⋮ More > Connect" inside the body.

This meant I didn't have to repeat having to find the symbol and format it correctly. Instead I inserted it from the Clip and formatted it again to fit in nicely 👩‍🍳👌

Finding ways to speed up the process like this can help make an almost unending task feel that little bit smaller.

So I was ready to replace all the more menus to make the step-by-step instructions make sense. Next up was the huge task of replacing all of the GIFs in the Knowledge Base.

Since the UI was a total overhaul they'd all need to be replaced. They're time-consuming to make but they mean customers don't have to hit play to watch a simple demonstration of carrying out the instructions.

To make this process easier I opened up a new desktop on my Mac, had a demo account ready and set up, and went about recording screencasts. From there it was just about clicking on the existing GIFs and replacing them inline.

Final Checks with Working Copy

With all this updating I was happy we released our Working Copy feature at the start of last year. It helped me update articles without pushing them live right away.

After a quick scan through each article I checked the metadata like the description, tags, and whether they needed a table of contents or not. Once I was reasonably happy I went ahead and hit Publish Changes.

If I wasn't quite ready to publish the article I kept it Stale and went back to it later.

Tips for Updating Your Own Knowledge Base

If you've ever had a massive overhaul of your own software you'll know it's no easy feat to update your Knowledge Base. Here are some things to consider:

• 📁 Is there a way you can organize your content before starting? It's a lot easier to get through the backlog of articles if you're organized beforehand. Exporting your data and using a spreadsheet could be a good option if your software doesn't have a feature to track it.
• 🐭 Set up a demo account. You won't want to show your—or even worse your customer's—data when you're recording videos, GIFs, or taking screenshots. Make a demo account to make sure you've got data in the account to make it authentic compared to a customer's account.
• 🖇️ Paste repeated snippets somewhere. To reduce the time you spend writing down the same content paste it somewhere you can quickly copy it later. An Apple note or Microsoft OneNote would do nicely.

With hundreds of articles to get through I'm happy I decided to get organized before I audited our Knowledge Base. It sure saved me a ton of time in the end.