What we learnt making a company wiki

For many companies, creating a wiki will seem like something that only larger, boring companies need to do. This may very well be the case, but there certainly reaches a point in the growth of an organisation, when some of the processes and structures are starting to coalesce, and doing things consistently starts taking precedent over constantly improvising.

When the amount of organisational knowledge hits this threshold — and this usually occurs when you are growing fast, and trying to do awesome stuff — it can suddenly become a major PITA to pass it on to new hires.

Technology

The information contained in the wiki matters more than the technology used to display it. It’s very easy to get hung up on this though.

We previously used Google docs as a lightweight system, but found a dedicated wiki much faster, and easier to edit. Now we use Github’s Gollum, with a couple of modifications:

• Google Apps OAuth integration, so everyone in the team has access
• Event logging to an internal system and a summary of edits sent via email daily
• Post-commit hooks to sync the wiki from our server to Github (as a read-only backup)

Where to start?

One of the daunting things when starting a wiki is knowing what information to try and document. I find it is often easy to start with a number of questions that people might want to ask about the company, and use that as the basis for the rest of the content. This will be a starting point, and the wiki will evolve a bit more organically from this.

• Who are the people?
• Are there different teams? Different departments?
• How does the company make money?
• What kind of customers do we have?
• How does management work? What kind of hierarchy exists?
• How is work defined and prioritised?
• What are the major projects?
• What internal services are available?
• What rituals does the company have?
• How are strategic priorities set?
• How do people communicate?
• What admin stuff exists (holidays, expenses etc)?
• What kind of processes does the company use?
• How do different teams do things differently?
• Who should you ask if you get stuck?
• What software tools are used by the company?

In our case, I call the system that answers these questions “the Pusher OS”, and it’s a way of working that we are constantly honing and improving.

Getting people to contribute

Wikis work best when there is a good amount of contribution from a number of different people. However, removing friction from contributing becomes a task in itself. Often people don’t want to make mistakes, and are a bit scared of screwing things up. For this reason, you may want to be explicit about what your policies are in terms of contributing, and where any kind of editorial oversight might exist.

One thing I’m trying is to make editing your “profile” pages a part of the induction process. This involves providing a template people can use to get the ball rolling:

• How to contact me
• Things/technology I am excited by
• Things I am responsible for in the company
• Things I tend to do as part of my daily routine

Structuring the information

While contributions are welcome, the structure of the wiki really matters. If things are chaotic, or hard to find, we experienced people using it less. At Pusher, I appointed myself as the single responsible person in charge of consistency (basically, the editor).

I’ve also tried to standardise the type of information needed on certain types of pages, and to almost create templates for other people to fill in. As I mentioned above, we often tend to use questions as the starting point for the area, imagining what people might be curious about.

For example, a page that describes a team, department, or area of responsibility might need to include the following minimum information:

• Who is responsible for this?
• What is the overall goal of this area?
• What kind of activities does it undertake?
• Who is involved?
• How are priorities set?
• How does this team measure success?

Discoverability

We’ve also found that people approach the wiki with very different levels of knowledge and expectations. The richness and depth of the information has to scale from getting a n00b introduced into the company, to an experienced member of the team looking something up as a reference. There are multiple ways of dealing with this.

Getting started guide

Our wiki has a section which is dedicated to getting people up to speed. This takes some of the decision-making out of the process of learning, and avoids the situation where people don’t know where to start. We’re working on a drip feed campaign for new people, that sends them more information as they become more familiar.

For example, it’s not useful to brief a new engineer on the on-call schedule and escalation procedures in their first week in the company. They will only be part of the on-call rota when they are familiar with the system, and teaching them about the process prematurely just worsens the signal to noise ratio.

Making it an effective reference

For experienced people in the company, we want the wiki to be a place they want to return to regularly. For this to occur, we aim to keep the information up to date, and also easy to find. A few other lessons have become increasingly important as we add more stuff to it:

• Have a useful search function
• Spend time on the structure of your home page, and be judicious with what you allow to be linked to
• Be mindful of the “guessableness” of your URLs

This last point proved an early lesson for me as the editor. I thought it was sensible to have pages nested in a directory structure, mostly for the sake of tidiness, but also to avoid name clashes (/engineering/process vs engineering-process).

Unfortunately, this was not a good idea, and my rule about it was questioned by the team. Now we are moving towards a single level of hierarchy, which works much better. The new standard is to make each page /<noun>, which can sometimes be a disambiguation page /onboarding -> /engineering-onboarding, /general-onboarding.

Going forward

The end goal of our wiki is to have a great store of good quality information. I’ll feel we’ve succeeded when someone builds a version of “let me google that for you” just for our internal wiki, and responds with it whenever someone fails to look in the wiki before asking a question :)

I’d very much encourage people to give it a try. Often the value from chronicling things only really becomes apparent when you start to write it down, and ask pointed questions.