Part I: How to choose the right tool for your docs

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

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.

Photo by Todd Quackenbush on Unsplash.

One part of my vision for our documentation is to develop simple and fast access to accurate product information. At FreshBooks, all of our Support team’s coveted product knowledge was housed in Confluence, which also included other content written by the rest of the company. However, finding Support-specific information in the vastly, hugely, mindbogglingly big wiki sea was neither simple, nor fast, for our Support team to access.

In fact, our Support agents dreaded using Confluence, and preferred to go ask their own colleagues or experts instead. We were also growing fast in several areas: in support volume; in new hires; and in releasing new improvements and updates more frequently.

When you connect all these dots together, it paints an alarming reality — our knowledge was too high-effort to use, and it was hurting our agents’ productivity. This in turn was hurting our customers, who were waiting on that knowledge. Our tool was not working well, and it was not supporting our documentation vision. It was time to look for something better.

Maybe you’re nodding in sympathy with our story, and you want to know how it ends. Or you’re at the same fateful crossroads of determining where to set up shop for all your docs and you don’t know where to begin. Either way, use these five steps to get started to identify a new tool, one that will actually allow your users to find and read all of your documentation.

1. Identify your users’ problems first

In order to look into alternatives to replace your current tool, start by proving there’s a problem first. If you have lots of anecdotal evidence like I did, it’s helpful to corroborate it with data from your users so that it’s easier to persuade your stakeholders (like your leadership team and/or executives) to say yes.

When it comes to collecting data, reframe it into questions that you want to see answered first. Once you have questions put together, you can then collect data to answer those questions, like a survey. I began with three key questions that I knew my stakeholders would ask:

Example of our Questions:

• What is the state of our docs currently?
• What are the specific problems affecting our users (Support)?
• What are the metrics I can measure to determine the new tool’s success?

And in case my stakeholders wanted specific data, I started thinking about how I could break up these questions to be more specific and targeted. From there, I came up with a survey of 4 questions that I sent out to our Customer Support team, one of which I left open-ended to collect testimonials:

1. How much do you trust the information on the wiki? (on a scale of 1–10)
2. How easy is it to find the information you need on the wiki? (on a scale of 1–10)
3. How often do you use the wiki on your cases? (on a scale of 1–10)
4. Any feedback on the wiki? Any things in particular that you find frustrating, or things you’d like to see improved?

Understand the problem first before finding a solution. Identifying what kind of problems you have will help you formulate a convincing argument to your stakeholders. The stronger your data is, the more compelling your request will be, and the harder it will be for your stakeholders to say no.

2. Synthesize the data with extra data

Obi-Wan Kenobi said it best, “your eyes can deceive you, don’t trust them.” Even though you may have identified problems based on your own survey or research, it helps to get extra data to paint a bigger and more accurate picture of the state of your docs today. Your stakeholders probably already utilize metrics related to the department’s efficiency, productivity and headcount, so why not use them too?

Utilize their data and merge any key elements that help supplement the data you’ve uncovered about the problems that you’re trying to prove. With your combined data, you should begin to see patterns or trends that can help you summarize your problems with key insights like these ones I uncovered:

Example of our Key Insights:

When I reached out to my stakeholders, I asked for access to their data — this included metrics like average cases per support agent, support headcount, how many wiki pages were owned by Support vs. other departments, and more. This, combined with the survey data, gave me the rest of the information to identify three key insights affecting our Support team:

Too Much Time on Cases (Poor Search)

• Our agents were spending 12% of their time trying to find information on our wiki every week
• A journey mapping session on agents’ workflows while working on support tickets revealed using the wiki was 1 of the 3 top pain points
• Our knowledge was getting drowned out, with 3% of all content in our wiki being support-related pages we needed our agents to reference daily

Too Much Dependency on Experts (Low Trust)

• Support agents were dependent on our Subject Matter Experts (SMEs), pinging them on Slack or in person for answers
• Qualitative data revealed that agents were making assumptions that if the top of the wiki page says “Last Updated by [Name] on [Date]”, it must be out of date… even if the information was still correct

3. Limited Functionality

• Support was already juggling multiple applications with our setup
• Onboarding was slow and laborious with learning various systems simultaneously
• A lack of analytics on Confluence meant we couldn’t track and improve searches, or see how certain content was performing/being utilized by our agents

Utilize your data effectively to maximize buy-in. Combine your data with other data that your stakeholders care about — this will help them see how this problem you’re raising may impact their metrics, or how a new tool could bring in improvements to certain metrics. Summarizing your data with key insights will help your stakeholders listen to you more carefully as you propose a new tool.

3. Establish requirements

Your next step is to then figure out what requirements you need for this new tool to be successful. It’s important to do this before you start looking at vendors for new tools. The last thing you want to do is to make a quick decision that could backfire — you don’t want the new tool to be a waste of your company’s funds and resources, or end up being ignored by your own Support agents.

• Focus on your audience — No single tool is right for all situations, and this is true even inside your company — what works for one department may not work for the other departments. It’s important to determine who will need access to your documentation first so you can understand which tool will work for your users.
• Separate must-haves and nice-to-haves — Understand what features are critical to your docs’ success and what are less critical but nice to have features. Separating them out will help you compare tools more fairly.
• Avoid unnecessary features — Don’t get sidetracked about shiny features that don’t actually address an actual need you have, and don’t put them down as a must-have.

For inspiration, check out business requirements by other departments at your company, or Google others’ lists of requirements like this one.

Example of our Requirements:

For us at FreshBooks, we wanted a tool that would be used by both Support and Sales to look at product information (basically, how does our product work). This would live separately from our company’s Confluence wiki, where a myriad of information that was not relevant to support could live. These were our hard requirements:

• User friendly — So that both our agents and any new hires so could pick it up quickly
• Integrates with Zendesk and Slack — It’s where Support spends most of their time daily
• Powerful search experience — We want to tag content and categorize, or reduce searching with machine learning/AI
• Isolated from Confluence Wiki — We want to ensure all the content is 100% support-related
• Bridges with external content (our Help Centre, which is hosted on Zendesk Guide) — To help decrease repetitive and redundant information
• Effective and robust content management — To easily scale as we grow in size and as we ship new features
• Analytics — So we can track usage and drive improvements, essentially creating a feedback loop to constantly improve the experience

Set expectations before you shop around. It’s easy to get caught up in the shiny bells and whistles that some tools offer compared to others, which is why setting your requirements beforehand is crucial. Knowing what features you need will help you evaluate each tool fairly, and you’ll be much more successful at finding the right tool to match your users’ needs.

4. Research all the tools!

When testing every tool out there, it’s helpful to have a comparison table ready that you can fill out with pros and cons for each tool, and each business requirement as its own row. This makes it easy to illustrate which tool scores best in each requirement, and if your stakeholders want to see the details of this comparative work, this table serves as excellent proof.

Test each tool against all your outlined requirements that you’ve put together in the previous step, and see how each performs compared to others. You can also give some requirements more points, so they’re scored more heavily in case you have to prioritize certain features over others.

You’ll also want to include these extra factors in your research:

• Support — Test the tool’s Support channels too — you should be able to get ahold of them easily when you need to, especially if you have questions, feature suggestions or feedback.
• Reliability — Look at the vendor’s Uptime — most tools should have a status page of their own; look at their history of downtime and issues; you want to be sure they’re as reliable as possible so that your documentation never doesn’t go down as often when your agents need it.
• Pricing — Get all pricing quotes in writing — you’ll need to compare costs with real numbers, not rough ballparks for your stakeholders.

Example of Tool Research:

In our case, I used icons for scoring and used a tally so I could quickly determine visually which tool met which requirements.

A snippet of our requirements with the final grade for each tool at the bottom.

The best decision is a well informed one. Doing your due diligence with research and comparisons across as many tools as you need will ensure that you are choosing the best tool to solve the problems you’ve identified. Having this information will also help you convince your stakeholders that the tool you’ve identified is worth the price if it meets the requirements you’ve established. Let the Force be strong with the tool you’ve chosen.

5. Next, persuade your stakeholders

Now that you’ve chosen the tool, you’ll need to convince your stakeholders to agree as well. If the price tag is hefty, you might even need to convince an executive too. You’ll likely have to put together a business case for this new tool in the form of a document or a presentation, which you might’ve never done before. At this point, you’ll want to do these things to ensure you maximize your stakeholders’ time:

• Drum up excitement — Don’t let your pitch be the first time your stakeholders hear about this new tool. Set the groundwork by mentioning it in team meetings, or keep your manager apprised of your progress so they can share it in high-level meetings, especially before budgeting season well in advance.
• Speak their language — Ask your stakeholders what they need to see in the proposal or slide deck, and use this to determine the outline of your business case. They may ask for financial information as well, like how much money would be saved with this new tool. If you’re new to crunching big picture numbers, your manager or a stakeholder you have a closer rapport with can help you out with this.

Example of a Business Case:

My powerfully persuasive pitch deck looked something like this:

1. Documentation Vision — The goal we’re trying to accomplish
2. Problems Facing our Department — A summary of the three key areas identified from the data
3. Needs & Requirements Identified — What matters to us when evaluating any tool
4. Tool Comparisons — A recap of the research completed and the comparisons between tools
5. The Winning Tool & Key Features — Background information on the new tool and their best features that met our key requirements
6. Metrics for Success — What data we would collect to measure the success of this new tool
7. Cost Breakdown — How much the tool would cost and any extra added fees
8. Q&A — Room for stakeholders to ask questions, objections and more

Win over your stakeholders with a compelling case. Summarize all your work so far with a business proposal or presentation that highlights the problems you’ve identified and why this new tool would solve all of them. Backing up your case with quantitative and qualitative data will make it easier for your stakeholders to say yes to effective documentation.

… and now the fun begins.

If you’re given the green light, now you get to begin the exciting second half of your journey — the big, great migration, and convincing the rest of your team to use this new tool! Read Part II here to learn more about how I got the new tool implemented for our Support department.

Are you considering a new tool or is your tool working really well for you? Let’s be each others’ Yodas and make documentation better for all.