The Basics

Before you dive into writing, here are a few core principles to help you create clear, useful, and easy-to-read documentation in Slite.

Start with your audience (ABC: Audience Before Content)

Audience Before Content. Consider the audience and the types of people who will be consuming your document. What are their needs, and what do they care about?
Someone on your team might require a lot more detail versus someone from another part of the business that just wants the highlights (but does need more context).

Make it visually engaging

Nothing scares people as much as a wall of text. Make use of the different elements that Slite offers out of the box. You can use "/" to explore, and consider adding /hint for summaries or /sketch to explain more complex flows in a visual way.

Structure your content with a clear flow

The content of your doc should flow smoothly guiding the reader through your content in a logical way. Here are some tips to help with that:
  • use a /hint block to add an intro at the top of the doc
  • use bullet points
  • start with the most important information at the top
  • add more details in the body of the doc

Use subheadings to guide readers

Subheadings tell a story, they inform you the user in a matter of seconds what the doc is about. They break up the text and will be used to form the table of contents automatically.
Headings (H1, H2, H3, H4) should be used to indicate the importance of a heading on the page. They should not be used stylistically to make text bigger or smaller. You can use colors, or make text bold if you want something to stand out.

Apply the ‘above-the-fold’ rule

Aim to make the main value point of your doc readable without the user having to scroll through the doc.

Re-order your content

If you believe your doc might become more readable after reorganization, you can simply drag and drop any of its blocks or even groups of selected blocks.
To reorder a block, hold the four-dot icon at the beginning of the line and then drag it to the desired position. You can also perform this action to move a group of selected blocks.

Improve your docs with feedback

Once your doc is ready, share it with your team. Great documentation is always evolving and a good way to share feedback is by using  ⁠⁠Comments on Docs ⁠ .