KB — Getting started — Authoring & style guide

Authoring & style guide researched

How we write KB pages so developers trust them and actually use them mid-build. Read this before authoring or editing any page.

Use this when

Creating a new page, or editing an existing one.

Definition of done

Voice

Write for a developer who is mid-task and short on time. Approachable here means low-friction to act on, not chatty. Use the imperative, in the present tense, and lead with the action: "Sanitize author HTML with DOMPurify," never "It is recommended that author-supplied HTML be sanitized." Keep the instruction up front and let the reasoning follow; a reader who already trusts you shouldn't have to wade through the why to reach the what.

Trust comes from claims a reader can check. "HubSpot accepts TLS 1.2+ by default" earns it; "HubSpot is secure" does not. Drop the marketing register and the filler that comes with it — "simply", "just", "powerful", "seamless". When something is uncertain, say so and mark it, rather than papering over the gap with confident prose.

We don't tag lines MUST, SHOULD, Required, or Recommended. Clear imperative writing carries the weight on its own. The Definition of done is where the hard rules live; elsewhere, words like "prefer" and "optional" do the signalling.

Rhythm

This is the part that makes a page feel written by a person rather than assembled by a machine. Reach for prose first and bullet lists rarely. A wall of dashes flattens everything to the same weight and strips out the connective logic — the because, the but, the so — that tells a reader how the points relate. Save lists for when the items genuinely are a set with no order or argument between them, like the page skeleton below.

Vary the length of your sentences. A long one that builds an idea, then a short one that lands it. Uniform sentences read as a drone; mixed ones keep attention. The same holds for paragraphs — two or three sentences is usually right, and a one-line paragraph, used sparingly, hits hard.

Cut repetition. If a word or a sentence shape recurs in adjacent lines, rewrite one of them. Say a thing once, in the strongest place, and trust it to hold. Brevity is the point: when a sentence carries no new information, delete it.

Sourcing

Cite what's contestable, not what's obvious. Any claim that is falsifiable or version-sensitive — a number, a platform limit, a specific behavior — gets an inline link to its primary source. General knowledge does not; citing "XSS is dangerous" only buries the citations that matter. The provenance runs page → report → source, so the Why & sources footer links the distilled /reports/<slug>.html and the upstream reference. Research reports themselves use the KB shape: clone _report-template.html into reports/ rather than hand-rolling standalone HTML.

Freshness & trust

A reader stops trusting the whole KB the first time they hit a confidently-wrong page, so make staleness visible. Every page wears a status pill beside its title — stub → draft → researched → published — and version-sensitive claims carry a date ("verified 2026-05") so a reader knows when to re-check. Platform behavior rots. An honest stub serves the reader better than a published page that has quietly gone wrong, so leave a page at its true status rather than overstating it.

Page anatomy

Every SOP follows the same skeleton, which _template.html ships. This is the one place a list earns its keep, because the parts are a fixed set:

• Use this when — the trigger, one sentence. It's what makes the page findable at the moment of need.
• Definition of done — the checkable gate, pinned near the top in an sf-callout. A reader should know from this alone whether their work complies.
• Steps (a procedure) or Requirements (a standard) — checkable, with copy-paste snippets where they help.
• Gotchas — platform-specific traps, in sf-callout--warn.
• Why & sources — rationale and citations, last.

Findability & adoption

Nobody is forced through this KB, so it has to be worth opening. That means indexing by the developer's moment rather than by topic: pages live under lifecycle phases, and the overview is a trigger router that sends "when you're doing X" to the right page — add every new page to it. Keep each page to roughly one screen of substance; if it scrolls forever it won't get read mid-task, so split or trim. And cross-link at the point a dependency bites, the way a form page points to the security baseline, so one page hands the reader to the next.

Workflow

The authoring commands and components palette live in README.md. The short version: clone _template.html into the right phase folder, edit the <head> and <main>, add a sidebar link and an overview-router row, then run ./build.sh — never bare pagekit sync — and pagekit preflight.