Courses How To Setup An Internal Knowledge Base Lesson 5

How to Write Documentation Your Team Will Actually Use

Jocko Willink, a former Navy SEAL officer and best-selling author, is no stranger to what it takes to build a high performance team. In his book, Extreme Ownership, he shares the 12 principles for becoming an effective leader.

Principal 6 is particularly important for setting up your internal knowledge base, but very easy to forget: keep it simple– Jocko Willink

Jocko Willink

“Simplifying as much as possible is crucial to success. When plans and orders are too complicated people may not understand them. When things go wrong, (and they inevitably DO go wrong), complexity compounds issues that can spiral out of control into total disaster.”

– Jocko Willink

In one tale of near-total disaster, Jocko shares how this principal helped save the lives of over a dozen U.S. and Iraqi troops. In the story, a team leader arrives fresh to Ramadi, one of the most dangerous cities in Iraq at the time. 

The leader’s first task was to go out on patrol, a usually straightforward mission. But this area was dangerous and Jocko knew that. Instead of greenlighting the mission, he asked the team leader to par down the scope and keep the patrol closer to home base.

The team leader reluctantly agreed, and it’s a good thing he did. The patrol ran into trouble almost immediately, and had to be saved by rescue vehicles. Had they gone out longer, it’s not a given that the rescue teams would have gotten there on time. 

Although sharing knowledge in a corporate setting is admittedly not nearly as important as making sure people stay alive in a war zone, the principle of keeping it simple applies to your internal knowledge base too.

Jocko explains that, “as a leader, it doesn’t matter how well you feel you have presented information or communicated an order, plan, tactic, or strategy. If your team doesn’t get it, you have not kept things simple and you have failed. You must be brief to ensure the lowest common denominator on the team understands.”

At Tettra, simplicity is one of our favorite values. Organizing information in Tettra is simple because there aren’t vast levels of hierarchy. Reading a page is simple because limited formatting options keep pages to be consistent. Searching for knowledge is simple because your team can access Tettra in Slack, where everyone is familiar with the interface. A lot of work has gone into making the product simple.

Even though the product is simple, it’s important to make sure you’re writing clear, concise, and simple documentation as a team too.

Here are some tips & tricks to writing readable documentation and making sure you’re using all of our editor’s features to their fullest potential:

Break up long pages into multiple pages

Your writing should be clear and to the point. If you’re outlining a particularly in-depth process, don’t be afraid to spread it out over multiple pages.

Readers often feel overwhelmed when they see long pages, so set up supporting pages for complex initiatives that help define terms, show specific processes, or break down the project by goals or teams. 

Once you’ve done this, create an internal page link using the `+` character in the page editor from your “master” doc to your supporting docs and pin it to your category. This helps isolate what information is the most useful to a particular person at any given moment.

screencast of internal links in tettra

Use headers

Another helpful tactic is to break up long pages with headers. In general, it’s a good rule of thumb to break up blocks of text with an image or header about every 400 words.

Not only do headers help you break up long form documentation, but they also help with searchability/readability. 

Headers on a page will be given higher ranks in your search results.

We also automatically add them to the page’s Table of Contents, so users can quickly scroll for the information they need from the left hand sidebar. 

Finally, although it might be fun to get creative with your headers, it’s good practice to avoid puns or undescriptive phrases for your documentation. You want the reader to be able to use the table of contents, search, or quickly scan the page for the information they need instead of guessing what to look for.

tettra table of contents screenshot

Callout important information

Another good tactic to use is the military technique Bottom Line, Up Front (BLUR), where conclusions and recommendations are placed at the beginning of the text rather than at the end. This helps people reading a page get the answer they need faster. 

You can even us Tettra’s Callout feature to really draw attention to a paragraph. Here’s how to do that:

tettra callout screencast

Use images, GIFs and embeds

A picture tells a thousand words, and a video tells a million. Wherever possible, add richer media (like screenshots, embedded videos, slide decks, tables, graphs, etc) to help orient people. 

Learn more about:

If you’re describing how to use a piece of software, try to include a video or gif of how to use it. If you’re telling people how to get somewhere, include an image of the map or route.

Checkout our integrations with various tools like Wistia, Google Drive, and more to learn more.

Create templates for routine work

If there are certain things you do again and again, make it easy for your team to document those items by using Templates

This will help your teammates feel confident they’re documenting information correctly and also keep your documentation structure more uniform. Here are some processes that other Tettra teams like to standardize with templates:

  • Weekly standups
  • Monthly or quarterly goals
  • Product briefs
  • Engineering sprint priorities
  • Marketing campaign components
  • Recruiting and hiring procedures
  • New hire onboarding tasks

Reference, Don’t Recreate

“Where’s that doc with the specs for this project?”

If you work on a digital team, chances are you get asked a similar question to the one above multiple times a day. 

The good news is that you can use the documents, emails, and chat archives that you already have to answer repetitive questions. Reusing your existing information is a great way to jumpstart your internal knowledge base to create a resource to answer questions asynchronously too. 

Importing: You can easily import a markdown or HTML file into Tettra. Learn more on how to import documents here. 

Copy & paste: If your existing information is scattered across various documents or web pages, try copy & pasting what you have into your internal knowledge base then editing it from there instead of writing from scratch. This will give you a base to work off of and help you fill up your IKB faster. With Tettra, you can paste in a Google Doc,Word file, or web page and most of the formatting should be carried over, which means you spend less time styling and more time writing.

Link or embed external docs: The most advanced way to reference is to use our integrations to link or embed your documents from other systems without importing or copy/pasting them at all.

Connecting G Suite to Tettra enables you to embed external Google Drive files right into Tettra. Once you’re connected, click NewExternal Doc, find the document you want to use, then click Add Link. Your document will now show up in the Tettra sidebar and also be searchable.

We’ll show you more on how to use our integrations to the fullest in the next lesson.

Your assignment

  • Add a screenshot, screen capture, or video to a page
  • Make a list of existing resources you plan to include in your internal knowledge base
  • Create a Template for a recurring process