Resources Articles

Wiki Best Practices: Top 10 Tips

Kristen Craft | February 8, 2019

Years ago, I joined a small tech startup, one with fewer than 20 people. The org structure was very flat, and there weren’t many rules about what people focused on and how they worked. On a good day, we applauded ourselves for being so nimble and flexible. On a bad day, we cursed the Wild West atmosphere that led to duplicated work, mistakes, and missed opportunities. As we grew, it became difficult to keep a finger on the pulse of what everyone was doing.

Everything changed when we began documenting our work in a systematic way. People knew who to call when bugs cropped up. It made us more productive. Perhaps most important, it gave the team better clarity about priorities. We knew what to focus on and how to spend our time. As businessman and best-selling author Stephen Covey put it, “When people are crystal clear about the most important priorities of the organization and team they work with…not only are they many times more productive, they discover they have the time they need.”

Good documentation also allowed people to collaborate more easily. You no longer had to be in the room to contribute to someone’s project plan. You didn’t miss out if you had to work from home on a snowy day. Introverted team members had more opportunities to contribute asynchronously. This more organized approach to our work paid off quickly.

There’s No Playbook for Good Documentation (Yet!)

Still, no one really teaches a growing team how to document things well. There were many factors that we overlooked in embracing a knowledge management system. We could have moved faster and been more successful, had we discovered certain best practices sooner.

Given Tettra’s position as the wiki of choice for over 30,000 people, we have unique insight into what makes for good documentation. We’ve seen the practices that can help or hinder a team’s success in building a culture of documentation. Our hope is that this list of best practices will allow more teams to reap the benefits of good documentation.

Top 10 Tips to Succeed with Documentation

Companies rarely go from zero documentation to a full-blown wiki. Many teams will start by documenting things in Google Docs or Quip or Evernote and then move onto something more robust. Whether you’re starting from scratch or already have resources scattered about, these tips will help you formalize how your team documents its work.

  1. Set the stage for your team

Add basic content to Tettra, so people have something to digest when you start adding people. Create some basic categories; many companies will create them around functions like product, engineering, or marketing. Others will structure them around common processes like billing, client onboarding, or vacation policies. Create 3-5 pages with a title and paragraph on each, so your team can envision how you’ll use your knowledge base. These pages could be basic info like your mailing address or how to submit an expense report.

2. Don’t let the perfect get in the way of the good

As you set the stage for your team, limit yourself to an hour or two. Don’t feel like you need to document everything before opening it up to others. Instead, aim for a decent baseline, (ie 3-5 categories and 3-5 pages) and then invite others to contribute. You can always add to it over time, as well as enlisting others on the team.

3. Get the group involved

Everyone on your team has something to share. Most likely, each person knows a piece of information or a process that others don’t know. Many people are working on projects that relate to others on the team in some way. Invite them to share this info! Encourage everyone to get involved and don’t let just one person “own” the content in your wiki.

4. Reference, don’t recreate

If you already have well-documented knowledge elsewhere, reference it on your Tettra pages. Try using our integrations to reference a Google doc.

Make an inline reference to the GitHub issue you’re working on. Embed a Google sheet on a Tettra page, so it’ll display there but will also update if you edit the original in Google Drive.

5. If you use Slack, use it to update the team about new documentation

Our Slack integration is one of Tettra’s most used features, and with good reason. It lets teams link Tettra categories in order to push updates into the relevant Slack channel. For instance, if you create a new Tettra page, documenting specs for a new feature, you can notify your “Product” channel when you publish the page. This means everyone can keep a finger on the pulse of what’s happening on the team.

6. Make it helpful from the first moment

When you add new people to your Tettra account, send them to a relevant page from within the invite panel. 

Help people get acclimated by directing their attention to a page they might use on the job. When you send an invite to someone, you can choose what they see first. We’ve found that people are 30% more likely to keep using Tettra if they see a useful page during their initial experience with the product.

7. Make suggestions to specific individuals

Think of some of the processes you use regularly. Who has the most knowledge about those processes? Create page suggestions for each one, and suggest that it gets assigned to those knowledgeable individuals. This practice creates three positive outcomes: it means that your documentation will be as accurate as possible, and it also fosters a sense of pride in people that they have knowledge no one else has. Last, having a DRI, (or directly responsible individual,) fosters a sense of accountability, ensuring that the process actually gets documented.

8. Document all processes with 3+ steps

We humans are forgetful. Mitigate forgetfulness by writing down any process with three or more steps. This saves you time when you onboard new employees, move people into new roles, or lose a longtime team member. As scientist and author, Atul Gawande, has research and written about in Checklist Manifesto, checklists for multi-steps processes eliminate mistakes and can even save lives.

9. Document anything you’ve repeated 3+ times

No one likes repeating themselves over and over. Save yourself time by writing down anything you’ve already said three times. If you’ve already answered a question three times, you’re highly likely to get the same question again. Similarly, Julia Grace, Senior Director of Infrastructure Engineering at Slack, reminds us that if you do something three times, it deserves to be documented.

You’re not only saving yourself effort by documenting anything you’ve done three times; you’re also making it easier to scale yourself, should you hire people to ask over parts of your work. Documenting common processes means you’re helping your team grow and thrive together.

10. Document any initiatives involving 3+ people

With more people comes more complexity. As this graphic below from Stack Overflow demonstrates, the lines of communication increase exponentially as more team members get involved in a project. This means there are more opportunities for confusion and stepping on one’s another’s toes. By documenting projects that have many people involved, you’ll not only reduce the downsides. You’ll also increase the chances that the project goes well. It becomes easier for people to get context, ask questions, and collaborate.

Learning from the Best

As a company, we’re always trying to learn what it takes to build a high-performance team. Luckily, with great customers like Wistia, HubSpot, Geckoboard, and Impulse Creative, among others, we get to learn from the best. We hear firsthand how they use Tettra to build a high-performance team. We’re grateful for the insights we get from the 30,000+ people who use our product. These best practices have allowed them to build a culture of documentation.

And yet, there’s still so much left to learn. Though there’s no official playbook for building great documentation, we’re excited to someday write and share it. But we’re just one small team. We can only gather best practices by learning what allows others to grow and thrive together. Please help us on this mission by sharing what you do on your team!