Knowledge bases

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.

#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.

✓

✓

Review state: PARTIAL. Editable in place, so keeping it honest costs nobody an editor session.

#Breaking a long page up

The single most useful structural macro for documentation is tabs. A concept, how-to, FAQ and troubleshooting set at the top of a page keeps a long article navigable without splitting it across four pages that nobody can find.

This is tab 1

This is tab 2

This is tab 3

#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*}

#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

Company intranet

A landing page people actually use.

Team/Project dashboard

Status at a glance.

Macros

Every macro used on this page.

Long pages need structure, not more pages.