At Tettra, simplicity is one of our favorite values. Organizing information in Tettra is simple with our intuitive structural hierarchy. Reading a page is simple because limited formatting options keep pages 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.

In that same vein, 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.

Use headers

Once you break up long pages into smaller ones, another useful tactic is to break up 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 to help with searchability/readability.. 

Tettra also automatically adds headers 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 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.

Callout important information up front

Another good tactic 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:

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:

• Embedding Google Docs, Slides, and Sheets
• How to embed videos and rich web content

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.

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 requirement docs
• 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. You can also try copy & pasting what you have into your internal knowledge base then editing it from there instead of writing from scratch.

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 Google Workspace to Tettra enables you to embed external Google Drive files right into Tettra. Once you’re connected, click New → External 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.