Reorganizing your knowledge base: a KnowledgeOwl case study

It can be hard to restructure or reorganize your knowledge base. Even if your current structure doesn't seem great, moving people's cheese and trying to get things set up in an intuitive way can be a daunting task. We recently underwent a total restructuring of our KnowledgeOwl support documentation, so we wanted to share that process and offer tips you can apply to your next knowledge base reorg.

A tale of two knowledge bases

When I started working at KnowledgeOwl, no one really "owned" our knowledge base or our documentation. It wasn't assigned to anyone or explicitly part of anyone's job. We just all helped with it here and there as we could.

Consequently, our documentation had been a bit haphazard: long periods where no one looked at or updated content, punctuated by frenzied flurries of activity where a lot of things would get updated.

We're a knowledge base company; we certainly know the importance of good documentation. But there are always a lot of other things to do, and without someone really owning documentation, even we battled this cycle. So if you're struggling getting traction for consistent updates to your docs: you are not alone!

I was hired in the fall of 2018. Though I'd been a KnowledgeOwl customer for years, it took me a while to learn the product from the inside out as a support person, rather than a user. Along the way, I leveraged our knowledge base a lot, to try to round out my knowledge.

As a new hire, I brought fresh eyes to our knowledge base's documentation as well as its layout.

I struggled with the four-category layout that the team had developed before my start date:

• Account administration
• Content management
• Knowledge base administration
• Developer documentation

(You can check out a snapshot of that structure courtesy of the Wayback Machine.)

I found that I often didn't understand the division between these categories. Did something belong in Content management or Knowledge base administration? (Turns out, we had a lot of things that fit both places.)

When I wrote new content, I had to ask the team where it should fit in the hierarchy. Often, I put it in two places because they both seemed logical.

This was a definite sign that the organizational structure was a bit unclear. I didn't feel certain about where I was putting anything, which meant that the structure didn't resonate with me. Since I was approaching the docs a bit like a new customer would, that was a sign of larger problems.

I didn't feel the four categories we'd agreed on were things that customers could easily relate to, and I imagined most customers did what I did to navigate the knowledge base: they just used search.

So that was our main problem: the organization didn't seem distinct and clear.

Context & usage

As I began to think about restructuring the knowledge base, I debated how I could or should structure it differently. Context and usage patterns matter, so I revisited those.

One of the things that makes our documentation challenging is that our product is used by companies ranging from solo individuals to global companies, managed by one person and managed by teams of people. There isn't necessarily a default workflow or a global set of admin roles. But our four category labels required that knowledge base readers had to try to identify with one of those categories. Since our customers are so varied, that was unlikely, so people were searching a lot more.

So roles weren't universal. But perhaps actions could be?

I also thought about how people come to our documentation. Our docs handle a variety of use cases and customers:

• Potential new customers
  • Product research: what features does KO have? How easy is it to use?
  • Software trials: where/how do I make xx changes or set up yy in my knowledge base?
• New customers or new hires at existing customers
  • What does KO do? How do I use it?
  • How can I get quickly oriented to KO and contribute on my team?
  • Where/how do I make xx changes or set up yy in my knowledge base?
• Existing customers
  • Where/how do I make xx changes or set up yy in my knowledge base?
  • I'm trying to do zz and it isn't working. What am I doing wrong? Is KO broken?
  • Is it possible to do ww with my knowledge base?
  • We've been using KO for [x amount of time]. Now that we've accomplished our original goals, how could we be getting more out of it? Are we overlooking useful features or functionality?

One way of organizing content here could be by customer type.

Realistically, for all groups, readers are only coming to our knowledge base to answer a specific question, learn how to do a specific task, or solve a specific problem. Their reading habits are very outcome- and action-focused. And you'll see there's a lot of overlap in the different customer groups. It wouldn't make sense for us to split out potential customers from existing customers, since many of the questions are the same.

So again: actions, rather than roles, seem important.

Straw man structure

With this loose guideline in mind (actions rather than roles), I made a copy of our current knowledge base, created four action-based categories, and started moving existing content into them, deleting duplicate content, and so on.

Top-level categories at this point were:

•  Creating content
• Changing the look and feel
• Configuring additional features
• Developing with KO

This felt a bit better but it also felt a bit forced, and there were some things (like our developer docs) that didn't seem to have an easy verb label.

But it was a straw man: the entire purpose was just to give my teammates and me something to react to.

Iterating

Over time, I showed this straw man to Catherine, our community manager (who wasn't doing support, so she was like a new customer), as well as Jerrard, our first hire after me. I got feedback from them and made some refinements. These two were basically my "potential/new customer" trial cases.

Eventually, after more fussing around, I showed the straw man to Marybeth and explained a bit of why I'd structured it that way. This allowed me to sanity-check what I'd done while getting feedback from someone else deeply invested in and knowledgeable about the docs.

As we talked, several things became clear:

• The action focus was already an improvement
• We found the gerunds ("-ing") a bit awkward
• We wanted to get away from words like "configuring", which felt a little formal and consultant-ey

Marybeth pointed out that she wanted to make it easy for people to find and learn about features they might not be using, and for people reviewing RFPs to have a features section where they could work through their own checklists. And, it turned out, she wasn't at all wedded to the four-category structure, which I thought was required.

So now the mandate wasn't just "fix the four categories we don't like". It now had style components:

• Wording should be in straightforward language, with easy labels
• No more role-based categories. Noun or verb phrases both work as long as they're clear
• Nix "configuring" anywhere it appears in top-level categories
• Keep the total number of categories to an even number, ideally one which will fit in two rows on the homepage

Four categories had forced an oversimplification that made the structure tricky. The flexibility of more categories gave me much more freedom and allowed me to focus more on good labels.

I made another round of changes to the straw man and then had Marybeth review it, so we could brainstorm the category titles more.

After a few more iterations (discussed more in How did we do it, really? below), we came up with the eight categories currently in our documentation:

• Write the docs
• Look and feel
• Features
• Search
• Reporting
• Security and permissions
• Account and billing
• API and webhooks

Putting it all together

With our new structure in hand, I used our test copy as a template. We blocked off a couple hours one evening so that I could rearrange our live KB to match that template. I also redirected deleted pages to their new/existing equivalents and got rid of a lot of redundant content that the reorg had surfaced.

Marybeth simultaneously worked on restyling the homepage a bit to better handle the doubling of the number of categories we displayed there.

Once we launched, I began a full content audit (still ongoing), working my way through each top-level category's content, updating as I went. This allowed me to proactively fill in gaps in places like Reporting and Features, where the categories had been a bit weak when we first reorganized.

I'm now, quite officially, the one owning our documentation. We've embedded documentation updates into our software release process, and we have established internal processes for other team members to report content that's in need of updating/writing.

How did we do it, really?

Coming up with those categories was a bit tricky, and there's no perfect equation you can follow to overhaul your own knowledge base. But here, in no particular order, are some of the ways we handled that process:

• We asked ourselves: What are the questions we're most often asked by new/prospective customers? From RFPs to demos, we considered what questions people most frequently asked--and how our documentation could help guide them to those answers without the need of a support ticket.
  • We get a lot of RFPs or emails from prospects asking if we support a big list of features, so we wanted Features to be easily accessible.
  • Security, access control, and permissions are often top of people's minds when they consider using KO, so we wanted to make it easy for people to find those options.
  • We have an existing "Getting Started" guide, but we wanted the home page to also help guide people to browse for basic usage information without throwing terminology at them they might not know. So, our content authoring category is actually Write the docs, and customizing style and branding became Look and feel.
• Then we considered our existing customers: What are our most common tickets from existing customers?
  • There are some questions that come up a lot: restricting access to view or edit content, for example, or what kind of reporting does KO provide. The documentation on these needed some overhauls, but they're so common that we wanted them as top-level, highly visible categories (both had previously been tucked away into Knowledge base administration). So Reporting and Security and permissions were born.
  • Customers of all stripes open a lot of tickets with us on tweaking or customizing the look and feel of their knowledge base--from individual articles to the knowledge base as a whole. Our previous layout put these only with the specific feature they applied to, which made it hard for readers to know all the available tweaks and customizations. We wanted to make these tips and tricks a lot easier to find, so we created Look and feel to gather them all together.
  • We'd already had a Developer documentation category, and in practice this was kind of like an "advanced" or "power" user category. But the phrase "Developer Documentation" seemed to discourage some people who weren't developers from exploring it. (It also contained some of our look and feel scripts, as well as a lot of information on SSO, which now lived with authentication and access.) So we updated the label to API and webhooks, to make it more descriptive.
• We also asked ourselves: If we could sit down with each of our current customers for an hour, which features or skills would we most want to teach them?
  • Customers who've been with us for years sometimes don't know that we rolled out awesome features since they first evaluated the product. It's also pretty common that a few months or years into a knowledge base implementation, customers start looking for ways they can "maximize" their use of KnowledgeOwl--and they ask about what other things they could be doing. We wanted a place to easily showcase features, so we made sure Features contained information on configuring features, besides just naming them. (I love this, because it means that potential customers explore the Features section and begin to learn the structure of our docs before they officially become customers, so the docs train them as they gather information.)
• We put together a straw man structure with temporary titles and then debated/reviewed them.
  • Naming things is hard. We needed to tap our collective genius to do this well.
  • We wanted succinct but descriptive titles.
  • We wanted titles with words that we liked. So if one of us didn't like a particular word (like "configuring"), we brainstormed alternatives. This might seem idiosyncratic, but the employees who eat, sleep, and breathe your product may have good intuition about words that work. Or don't.
• We tested the new structure. When we had come to what we thought was the final structure and titles for the categories, I reorganized all of our existing content in a copy of our knowledge base into those categories. Marybeth pulled up our current documentation. We picked a handful of articles at random on the existing site and then Marybeth guessed where the article now lived in the restructuring.
  • I cannot stress how useful this exercise was. It validated our theory of the new categories. In most of the cases, she guessed right on the first try (the one exception was an article that I'd put synchronized copies of in two places, since it fit equally well in both--we confirmed that the location she'd guessed was one of those two places).
  • We then talked about why each article belonged where she'd guessed and where I put it. This helped crystallize what each category "meant"--what it was for, what type of content lived there. We internalized the structure more, found the couple places where it still felt a little off, and changed them.
  • Thanks to that deeper understanding of our structure, we also finessed the category titles a bit more.

Takeaways you can use

In no particular order:

1. New hires or new-to-your-department transfers are a wealth of useful feedback. These are non-customers who have to learn your product and your documentation. They're a lot like canaries in the coal mine: where they struggle, you can imagine a new customer will struggle. Use their feedback to help highlight issues with your current organization or docs.
2. Have a clear sense of what problems your documentation is trying to solve. In our case, our docs help answer questions from potential new customers, help orient and introduce new customers to our product, help existing customers learn more about the product, and should help customers answer questions and fix things without having to open a support ticket.
3. If possible, list out what isn't working in your current layout. You know the problems your docs are trying to solve; which ones aren't they doing a good job of solving? Sometimes restructuring doesn't help with this--if, for example, the problem is outdated content, reorganizing is just like rearranging the deck chairs on the Titanic. Invest your efforts elsewhere.
4. Use a straw man. The KO team indulges me because I use a straw man for nearly everything. But in my experience, it's much easier to get feedback on something when people can see it and test it than when you just talk at them. Talk is cheap. Work up a prototype, a wireframe, or a reworked copy of the knowledge base. Give people something concrete to react to. It will boost involvement: everyone can see it start to take shape, and you can get far more pointed feedback and criticism.
5. Don't forget about branding/design guides. We spent much of 2019 working with a design firm to rethink our public website and branding. I've been the one managing that engagement and pushing things forward. Because I led the restructuring effort, we naturally incorporated some of the brand/style guidelines we have for the upcoming new KO website into our knowledge base redesign. If you have internal designers and brand specialists, or an internal brand or style guide, use those resources! This can help keep a more consistent experience across your entire web presence and can save you valuable time and effort. You don't have to reinvent the wheel.
6. Test the reorg. This was not part of my initial plan when we began doing the restructuring, but when Marybeth started guessing where commonly referenced articles would live, it increased our confidence that this structure was an improvement over our existing structure. It helped us refine wording and sanity-check that we were on the same page. It helped us internalize what the new structure "meant" and make sure we understood it the same way.
7. Refine after launch. Don't treat the initial go-live of the restructure as the final word. Reorganizing can draw greater scrutiny to your documentation. Be prepared to make additional refinements and updates after you launch.
8. Stay open to feedback. It's always a risk moving people's cheese. Each time I sought input, I had to remain open and willing to hear it, and to let go of ideas I might have had about "my" structure of the knowledge base, so that "our" structure could move forward. And once we launched, I braced myself for negative feedback or questions. The process to create the new structure has made me internalize the structure more, which gives me a better rationale and method for incorporating suggestions or feedback we receive. It's a win-win.
9. Use the restructuring as a springboard for larger documentation workflow and process conversations. We didn't love our existing KB structure. I think the common sentiment was: "Let's burn this to the ground and start over." We found it a bit embarrassing, and we wanted it to be better. With the new structure, the team is energized to do more with our docs. We've harnessed that energy to update our internal software development and release workflows to require documentation updates--so nothing should slip through the cracks.

Hopefully sharing some of our ups and downs can help you make your next knowledge base reorganization run a bit more smoothly!