​

Docs Style Guide

This page is the standard for future docs work in this repository. Use it when you write a new page, revise an existing one, or decide whether a fact belongs in product docs or operating docs.

​

Scope

The docs site has three distinct surfaces:

• Tremor landing is the curated front door. It exists for orientation, thesis, and the company story.
• Paperclip product and control-plane docs explain the platform, its contracts, and its stable behavior.
• Tremor operating docs explain how the current Tremor company is run, audited, and recovered in practice. In this repo, that surface is the operating/* section, backed by the company corpus in companies/tremor/*.

Those surfaces are related, but they are not interchangeable.

​

Writing Rules

• Lead with the user outcome or system purpose in the first paragraph.
• Keep one page focused on one job.
• Use Paperclip for the platform, control plane, and product concepts.
• Use Tremor for the current company, its operating corpus, and time-bound audit facts.
• Keep the Tremor landing page short, curated, and link-heavy rather than exhaustive.
• Prefer short sections with one idea each.
• Use explicit dates when a page records live state or an audit snapshot.
• Separate timeless contracts from current-instance facts.
• Avoid mixing “how the platform works” with “how Tremor is currently being operated” unless the page is explicitly a boundary page.

​

Page Types

Use the right document shape for the job:

​

Presentation Conventions

• Use tables for comparisons, decision matrices, and authority maps.
• Use cards for navigation surfaces and “what to read next” blocks.
• Use diagrams for topology, data flow, and boundary clarity.
• Use ordered lists for procedures.
• Use callouts only when a warning, constraint, or exception materially changes the reader’s behavior.
• Keep screenshots and illustrations rare and purposeful.
• Reserve editorial or theatrical framing for the landing page only.

​

Boundary Rules

• If the page defines a platform contract, it belongs in product docs.
• If the page records current runtime, repo, environment, or audit facts, it belongs in operating docs.
• If the page exists only to orient a new reader, it belongs on the landing page and should link out quickly.
• If a fact changes because a runtime or baseline was promoted, it is operating material.
• If a fact changes because the platform changed for all users, it is product material.
• If a page compares both, say so in the opening section and label the boundary clearly.

​

Style Rules

• Use sentence-case headings.
• Prefer plain markdown over heavy custom components unless the component improves comprehension.
• Keep prose direct and operational.
• Keep landing prose tighter and more selective than manual prose.
• Name things exactly. Do not alternate between similar terms when one is canonical.
• Avoid decorative diagrams. Every Mermaid block should explain a relationship, flow, or boundary.
• Avoid long nested lists unless the page is procedural.

​

Recommended Page Skeleton

Use this order unless the page type clearly demands something else:

1. Title and one-line summary.
2. Opening paragraph with the user outcome or the reason the page exists.
3. Boundary statement if the page touches both product and operating concerns.
4. One diagram or one table that orients the reader.
5. The main content.
6. Related pages or next steps.

​

Current Standard

For now, this is the canonical working rule:

• if the reader is deciding, use a table
• if the reader is navigating, use a card
• if the reader is learning a process, use ordered steps
• if the reader is understanding a system, use one diagram before the prose

​

Related Pages