Knowledge bases

Updated
View as text
Open in Confluence
Open in ChatGPT Open in Claude

Knowledge bases are the hardest test of a formatting pack. Pages are long, mix prose with code and diagrams, and have to stay navigable. This page is built the way one of ours is.

Team working together

New here? Start with the guide

Setup steps, templates, and FAQs for your first week.

Open the guide

#Where this article has got to

A progress tracker at the top of a documentation page tells a reader whether they are looking at a draft or something reviewed.

✓
Plan
✓
Build
3
Test
4
Review
5
Release

Review state: PARTIAL. You can change it straight from the page, so keeping it honest never means opening the editor.

Progress tracker macro with five steps from Plan to Release, Test set as the current step, and the steps list in the Try it out panel
The same five steps as the tracker above. Add, reorder or remove steps on the right, and pick the current step at the bottom.

#Breaking a long page up

Tabs are the most useful structural macro for documentation. Put a concept, how-to, FAQ and troubleshooting section in tabs at the top of a page and a long article stays easy to navigate, without splitting it across four pages that nobody can find.

This is tab 1

This is tab 2

This is tab 3

Tab Group macro with Overview, Purpose and More info tabs, and settings for tab alignment, container border and orientation
Tab Group settings. Choose where the tabs sit, whether a border wraps the content, and whether the tabs run across or down.

#Code and maths

Technical pages need both, and both need to be readable rather than pasted as screenshots.

{
  "name": "team-space",
  "labels": ["documentation", "engineering"],
  "permissions": {
    "view": "logged-in",
    "edit": "space-admins"
  }
}
x2+y2=1y=1−x2\begin{align*} x^2 + y^2 &= 1 \\ y &= \sqrt{1 - x^2} \end{align*}x2+y2y​=1=1−x2​​
LaTeX macro showing the equations from this page in the preview, with their LaTeX source in the Text editor on the right
The equations above, as typed into the LaTeX macro. Type the source in the Text tab, or switch to Live to build it visually.

#Citing sources

Footnotes keep a claim readable while still supporting it[1], and the markers collect into a summary at the foot of the page rather than interrupting the sentence.

#Which macros this page uses

Section

Macro

Why that one

Header

Banner

Gives a long article a recognisable top

Article state

Progress tracker

Tells a reader whether this is a draft

Review state

Status badge

Inline, editable without opening the editor

Structure

Tabs

Four sections without four pages

Content

Code and LaTeX

Readable, selectable, and searchable

Sources

Footnote

Support a claim without breaking the sentence

Long pages need structure, not more pages.