Your wiki doesn’t suck. Your wiki entry points suck.

The Symptoms of a Wiki that Sucks

Everywhere I have worked, the wiki (or internal documentation) has sucked.

The common statements sound like these:

“No one can find anything, because it’s so disorganized.”

“It’s overwhelming”

“The wiki isn’t worth it, I’m just going to use Google Docs”

“I write things down, but no one reads them”

Yep. Confirmed. That sucks.

What does this look like?

When I am in a wiki and need to find something, I’ll try the search — but then 17 documents with the same name come up and I can’t figure out which one I need. Sometimes, if I am lucky, there is enough information in the search results to help me find something but the reality is that most often I am doomed to open up multiple items until I find the thing, or not.

It’s frustrating and a waste of time. Depending on how the search works, which is often implemented with best intentions — if someone changes one of the files or opens it, it shows up at the top of the search — which only makes the problem worse because the wrong things are showing up!

What can we do about it?

I have seen attempts at fixing the problem. They are all bandaids that don’t take into account the inertial nature of humans to do the same thing over and over, regardless of the result. This inertial nature is our default when we are overwhelmed and “just trying to get something done.” We’re reacting to the situation and we aren’t in our logical mind. Whether we want to admit it or recognize it, we are often stressed out and reacting. This means we will try the first thing that comes to mind and often that first thing doesn’t work and keeps us reacting rather than thinking.

This totally normal behavior is so inefficient! As a Product Manager, I can’t help but look at the symptoms, the problems, attempted solutions, and then draw on what I have discovered to find a valuable solution.

Bandaid Solution 1: Every team gets a space

This is often the setup that most tech companies start with.

It works until multiple teams are working on the same thing and there’s no expectation set on how docs get shared, where they live, or what they are for.

In the same way you don’t (or do you??) go through other people’s cabinets in their house, it feels weird being in someone else’s space. You don’t know what’s active or not. You aren’t totally sure how these crazy people get anything done with their wiki organized like this! Maybe that’s because they do a different job and think about things differently than you!!??)

Bandaid Solution 2: Create your own personal space in the wiki

Whenever I start a new job or start messing about in a company wiki, I make usage of the personal or private pages in wikis, because I have accidentally messed things up and people understandably get really upset about it.

“Matt’s Space” quickly becomes where I put everything, because I no longer need to learn where other people are creating things. I keep links to important documents, a list of questions to answer, meeting notes, and other data that might be relevant to me. When I create my own docs in this space that need to be shared, I often forget to set the permissions for people to see the docs and then coworkers start to wonder what else I am keeping a secret.

If I identify established central place for “this kind of doc” I will move my stuff and just link from my central page. This helps ME to be more efficient, but it isn’t a good solution for anyone else. It also can undermine the collaboration that I work so hard to build in one quick completely unintentional way when I accidentally share a doc that doesn’t need to be private but was set that way by default.

Bandaid 3: Hire a team to fix it

Best intentions, hire the experts. Works every time, right?

Hiring a team can be expensive, time consuming (read:slow to see actual measurable results). The worst part of this, is that everyone else in the org often is made to comply to whatever new system was thrust on them which is often intuitive only for the experts.

This can work, or at least I have heard it can. There wouldn’t be experts who do this if it didn’t work. The problem is that it’s going to be painful for your established teams, for your experts, and it’s a slow down to speed up answer and a lot of people are too impatient for that sort of thing.

A better solution exists!

I mean, duh. Why else would I write this? I like to bring solutions, because my experience shouting into the ether has had zero positive results.

The reason Google is the entry point for everything, is because they have spend billions of dollars creating a field and algorithm that guarantees the most relevant results for your search. Most of the time, the success rate is good enough that Google wins over other options.

Libraries used to have card catalogs, then they switched to databases. Maps and yellow pages used to be great, but search + maps improved the entire situation by laying the results on the map and giving you distances, opening times, and ratings. Folks are now incentivized to optimize their websites and businesses, so that they are discoverable.

Your wiki search is not Google. It’s difficult to make search work well when there are 7 documents named the similar things because they are all related. Your wiki is not a curated library, because very few people in this world are going to spend the time or effort to make it so.

Let’s make some concessions and take small steps to make things a little easier for the humans involved. You can set up the potential for a curated and discoverable environment by making your wiki do some of the work for you and use a human’s tendency towards simplicity to make things easier.

When you don’t have the authority to ask people to try a new thing, I am firm believer in giving first, testing things on my self publicly, and collaboration rather than helping people change by fiat. I will share what I am trying with my team and welcome anyone who wants to try it out.

Another thing I have found is that no one wants to go backwards and update old projects or projects in flight to a new system. That’s fine! The ROI is often awful on going back through everything and matching it up to a new system. Do the minimum to continue to make it easy to find the old stuff through the new system, don’t migrate things. If you’re feeling adventurous, you can help someone set themselves up to try it out.

Setting things up

Step 1: Make it easy to create similar docs in the same place

1. Make templates as you discover document types in your org — this makes it easier to create those kinds of docs. Don’t be a stickler about the format, let people try new things. It often results in removing the stuff that doesn’t matter and adding things that do.
2. Where you put the template matters. In most modern wikis, you can add a button that will create a document with a template and the document will be automatically created in a tree structure. Now all the docs of this kind are together from now on.

Step 2: If there are many of the same kind of doc, create multiple views

I will use project docs as the example here, but the idea applies to any kind of doc you might keep in a wiki.

When you have pages and pages of docs, finding the right one just went out the window again.

Create views of the documents, based on their meta data:

1. Create a view that sorts all docs by “Most recent” first
2. Add a status field to your doc, then create a view that sorts the docs by statuses, e.g. Backlog, In Progress, and Done. Then, sort or group the docs based on the statuses.

Step 3: Create/update project and team hubs

Humans will only remember so much, make it easier to find what they need when they need it. It is rare that a single document covers the entire project, especially when you have multiple people working on it together.

Your company probably already has a team hierarchy. One the team homepage or a consistent sub-page for every team, you can embed a view of all the projects the team is working on.

If you have projects that take a little while or involve multiple people, creating a place for all projects to live, along with a button that can create a templated hub for each project will make a huge difference. Organizing the template to the incentives of potential viewers will mean more people are likely to be able to find what they need regardless of the project.

Step 4: Use the wiki’s functionality to save you time

Most wikis have ways to generate “reports”, “sub-lists”, “collections” or whatever they want to call it based on document meta data that you control.

This is a way to take what you did in step 1, add an extra parameter, then generate a list of those documents anywhere you want based on meta data values.

For example, in Step 2 you setup a team hub. Rather than having to remember to link every project doc to your team hub, embed a dynamic document list and set the meta data to show docs where team=YourTeam and sort or filter by created date or status. You can do this for a project hub too, where you add project field to your docs and select or enter a project name. Often, as a bonus in some wikis, creating docs from these views auto-sets the params you filtered on so you can save time by creating them from the hub.

Step 5: Behavioral reinforcement

Whenever possible link to the hub which links to the doc. This will reinforce the value of the hub. Sometimes it makes more sense to link directly to the doc rather than the hub, so it is helpful to have the link to the hub at the top of the doc. Both of these actions reinforce the hub as the entry point for the project, because all roads lead to the hub.

Some Background On This Approach

I have been setting up similar systems for years because I would lose my mind in wikis at different jobs. The concept was reinforced for me when I started looking into The Zettelkasten Method, Commonplace books, and Building a Second Brain. Which to summarize loosely is all about keeping a ton of information outside of your brain in a way that is more similar to how your brain works.

The trick with the Second Brain methods, is making the information easy to discover as you work. The entry points matter. By creating intuitive entry points, you can dynamically link to similar information quickly and then review that information together. In effect, you’re creating a heterarchy of data and using it to navigate and explore the information you’ve saved in your Second Brain.

A wiki can be the same thing, but often falls down because humans think about storing and accessing data uniquely.

Humans are great at learning and following a pattern especially when that pattern is beneficial to their goals.

At work, most folk’s goals are to find, read, and move on quickly. So, creating a small amount of process around the creation of documents, projects, and teams will pay dividends towards the discoverability and findability of the information for everyone involved.