Chapter 
5

Wiki Design

Some of the most beautiful buildings in the world are libraries. Think Trinity College Dublin, Tianjin Binhai or The Royal Portuguese Reading Room. One of the great joys of walking into a library, besides the hush of intellectual activity and breathtaking architecture, is the fact that going in, you know you'll be able to find whatever book or resource you're looking for. Just like a wiki site, librarians store information to be accessed and used with frequency, always put back in the same place for the next person to find it.

Source: Mayumi Ishikawa /Wikimedia Commons

Some library systems are more efficient than others. For instance, the Joe and Rika Mansueto Library at the University of Chicago has a set of robotic cranes that retrieve resources in 3 minutes, on average. This short wait time frees up scholars' time to do their academic research.

A well-designed wiki site functions like a great library: as a useful aid to productivity, and a calm environment to get work done. With the help of great wiki software, designing a functional and delightful wiki doesn't take much time at all.

What to keep in mind before designing a wiki

At the start of any collaborative effort, it helps to set ground rules. A team wiki is no different. Before designing your wiki, draw up a list of organizing principles. Many wiki softwares, built to be "opinionated," have organizing principles baked in. For instance, Slite software favors simplicity over customizability.

Ward Cunningham, the creator of the first wiki website, gathered a list of 15 design principles for WikiWikiWeb. Some of these include: simple (a popular one!), open, incremental, and organic.

When it comes to our own wiki in Slite, we follow a loose set of best practices. Some of these include:

  • Differentiate between"stock" (processes) and "flow" (daily work)
  • Keep all documents up to date
  • Archive documents that are no longer useful
  • Add context to documents, such as TL;DRs, collection info, cover videos and author
  • Automate recurring workflows

Here's an example of a real 1:1 review doc with all the above put into practice. It's part of a "stock" process, so the template is the same for each meeting.

A well-designed wiki page is one that gets read.

Of course, you can iterate on the rules over time - after discovering what works for you.

How to prepare for the design process

Luckily, with so many wiki software tools available, you don't have to design your wiki site from the ground up. The basic architecture already exists in the wiki platform. In Slite, you'll basically be working with two design elements to create your own wiki:

  • Channels: categories of documents
  • Documents: individual notes

You also have the option to nest documents. Nested docs are those that are linked within other documents.

Creating a simple hierarchy is the first step to wiki design

In most wiki tools nowadays, there's no code required, making information design especially easy for non-technical leaders.

Wiki Design Best Practices

You've already learned how to create a wiki, but just in case, a quick refresher on the how-to:

  1. Set wiki goals
  2. Choose a wiki software
  3. Identify key contributors
  4. Create an outline
  5. Have a kickoff meeting

Now it's finally time to design the wiki itself, starting with the overall structure.

Name your channels

If you're creating a general team wiki, we recommend structuring channels by teams, such as Development, HR, Marketing, etc. These are natural categories in your organization, with leadership built in. This structure encourages individual ownership and is a better guarantee that your knowledge will stay up to date as new team members are added.

A lot of new companies and startups value transparency. We do, too. The goal is to share knowledge, not keep it siloed. Therefore, keep each channel open to create more opportunities for collaboration and reduce workflow inefficiency.

Our Marketing channel is open to everyone at the company

Now, what do we put in those channels?

Write actionable documents

In a wiki, you're creating content for an audience of your team members - and you want them to read them! To do that, you need to focus on documents that are actually useful and will help them do their jobs.

The writer's greatest enemy is the blank page. Luckily, we've got lots of resources to help you avoid it.

Slite Templates have your back.
  1. Try a template: Start with one of our 100+ Slite templates sorted by team type
  2. Get inspired: When it comes to docs, why reinvent the wheel? Check out Startup Bibles to learn about how Intercom, Netflix, Stripe and other successful startups set up onboarding, team handbooks, and internal processes
  3. Learn: How to write a good note? This is our own quick writing guide for documentation in a wiki.
Want to kick-start your wiki design? Try a free Slite template-->

Standardize your channel structure

A good practice of taxonomy (think the animal kingdom!) is to name and structure each team channel the same way. It makes it easier to map out information, and thus makes information easy to find. In that case, the Development channel will look fairly similar to the Marketing one:

Best Practice: Standardize naming so that docs are easily findable, even without search.

Of course, individual teams do not always have the same set of processes, so certain documents will have to be different. But following a generally similar structure across your wiki channels will make working across departments a whole lot easier.

Set clear ownership and permissions

Even though wikis are community projects, administrators play a key role in wiki success.

As mentioned above, team leaders are a natural fit to manage their department's channel. They will be in charge of doc creation, keeping docs up to date, automation where possible, and archiving old information.

That doesn't mean individual contributors can't add to and edit the wiki, however. In Slite, you can adjust sharing at two levels: channel, and document.

For channels: Just tap on the the channel settings in the sidebar.

For documents: Adjust sharing permissions with the blue Share button at the top of a doc

Document sharing permissions in Slite

You can make someone a reader, writer, or admin of a document. These options make it possible to keep your wiki open while also controlling the flow of information.

As a best practice, we recommend that if a team member creates a new page or document in a shared channel, they put their author name at the top.

If you want, you can create groups of users to manage permissions at scale. This way, everyone can stay on the same page.

Document Design Best Practices

Now that you have some idea of how to structure the wiki itself, let's get into document design. We think this list is a lot like Stephen King's rules for writing, but for businesses online. In the interest of clear writing, we'll keep this brief.

Write concisely

Consider if you were writing a note to yourself. How would you want that note to read? 

  • Stick to short, sharp sentences.
  • Put the most important info at the top
  • Try to avoid any jargon that may confuse your reader.
  • Use bullet points where possible.
Already a pro writer? Create your first document in Slite-->

Use images and screenshots

Whenever you're struggling to get your point across in a wiki article, consider a visual. At Slite, we particularly like using sketches to express our ideas.

Sketch directly in your wiki to capture your colleagues' attention

Structure and categorize information

So crucial for searchers. Build out a wiki map that's searchable by category or keywords. This includes focusing documents around one main topic and always using headers, such as H1, H2s, and H3s to organize content.

Format wiki pages as if you were going to publish them

Beautiful documents are underrated. When a document looks nice (see aforementioned images and headers), people are more inclined to read what you have to say. Wiki pages don't have to look like boring text documents - they can include rich text elements such as highlights, code snippets, block quotations and hints.

These Release notes use hints, headers, images, and bullets to get ideas across clearly

Rich text makes your ideas more compelling.

Share it with the right people

For the sake of transparency, it's great to make your wiki publicly accessible to everyone in your team. That doesn't mean everyone needs to be inundated with notifications. Utilize features like tagging, pinging, and permissions toggles to make sure the right people are getting notified when you update a wiki page.

Get others to contribute

You don't need to create pages alone; in fact, it's better with specialists. Figure out who they are and ask them to contribute to a wiki page by inviting or tagging them directly in the document.

Review content and edit for clarity

When you start collecting your wiki content, it should all go through an editing and review process. Some team members will likely be stronger writers than others. You'll need to make sure that there aren't any errors, inaccurate information or unnecessary sections.

Also, as your company grows and you add new team members, you'll probably be creating more and more wiki pages. And with some wiki platforms featuring unlimited pages, you'll start to see the number of documents grow quickly.

The best content for your future wiki users and viewers will be clear, concise, and accurate. Avoid including information that's overly long-winded or confusing. And review the whole wiki periodically to remove outdated and duplicate pages.

Test your internal wiki with your team

As with any design process, you need to validate your wiki site before launching it into the world. Before your wiki is 100% ready to go, you'll want to do some testing. At the end of the day, a company wiki should be a useful tool that's easy to navigate, not something that causes confusion and headache.

Assemble a group of people from your company that can beta-test your new wiki. It's best if these people did not work on the development of your wiki so they're looking at it with fresh eyes.

Be sure to ask your testing group the following questions:

  • Is there any missing information? What knowledge gaps stand out?
  • Is the wiki easy to navigate? If there are any, what navigation or design problems come up?
  • What general challenges do they face with the wiki?
  • Is the wiki organized in a logical way? How could it be improved?

Design your wiki for everyday use

After you've launched your wiki, most of your colleagues will start as students. It will take them time to fully integrate your company wiki as part of their regular work habits. As such, it's important to set a good example and remind coworkers to consult the wiki as a first step to seeking out information.

Habits are built day by day. If someone requests information via email, Slack, or in-person, be sure to direct them to the wiki in order to get them into the habit of using it as a resource. If you notice that there's missing information in the wiki and you know one of your company's employees has the answer, be sure to ask them to click that "edit" button and fill the knowledge gap themselves.

Last, if you're making any changes to the wiki down the road, be sure to keep your coworkers in the loop.

Melanie Broder
Written by

Melanie Broder is on the Marketing team at Slite, where she works on all things content. She helps Slite users gain new skills through guides, templates, and videos. She lives in New York City, where she likes to read novels and run loops around Central Park.

You
Bring your team on the same page.
Get started