Style guide¶
The goal is that every page reads as though one person wrote it. These are the conventions that get us there.
Voice¶
Write to the reader as "you". Use "we" only for things GRN does, and sparingly.
Say what a thing is before saying what it does. A reader who does not know what an MCP server is cannot follow instructions for deploying one.
Prefer the plain word. "Use", not "utilise". "Delete", not "deprovision". "Before", not "prior to".
Do not sell. State limits plainly. A limit the reader finds for themselves, after following a page that did not mention it, discredits the rest of the page.
Structure¶
Every page opens with one or two sentences saying what the page is for. No preamble about how important the topic is.
| Page type | Shape |
|---|---|
| Product | What it is → capabilities → how it fits together → related |
| Tutorial | Goal → prerequisites → numbered steps → verify → clean up → next |
| Console walkthrough | Companion to a tutorial — same numbering, real screenshots, plus a section on where the console differs from the CLI |
| Reference | Tables and signatures; no narrative |
| Runbook | When to use → impact → prerequisites → procedure → verify → rollback |
| Troubleshooting | Symptom → likely cause → check → fix |
Headings are sentence case: "Add a model provider", not "Add A Model Provider".
Commands and output¶
Only document commands you have run. Never invent output. If a flow has not been verified yet, say so in a note rather than writing plausible-looking results.
Use <angle-brackets> for values the reader substitutes. Do not use fake-real values
like acme-corp — readers copy them.
Annotate what the reader should see when it is not obvious, rather than pasting a full terminal transcript.
Screenshots¶
Screenshots live in docs/assets/screenshots/<tutorial-slug>/, named
console-01-<what-it-shows>.png and numbered in page order, so the filename sorts the way
the walkthrough reads. Crop to the console panel being described rather than the whole
desktop, and capture in the light theme so they stay legible in both site themes.
Real captures only. Never a mockup, a redraw, or an illustration of a screen that does not exist yet. A console walkthrough is evidence that the flow works, and a drawn screen is not evidence of anything. Redact tokens, keys, internal hostnames and customer identifiers before committing.
Admonitions¶
Use them sparingly. A page with a warning on every section has no warnings.
| Type | For |
|---|---|
!!! note |
Context the reader can skip |
!!! tip |
A better way to do what they are already doing |
!!! warning |
Something that will cost them time or data if ignored |
!!! console |
The same operation in the web console |
!!! cli |
The same operation with oc |
The title states the fact or the condition inside the box, not a slogan about it:
!!! warning "Nesting grants the parent group's access to every member", not
!!! warning "Nesting is also the easy mistake".
??? instead of !!! makes any of them collapsible, for depth a subset of readers wants
and the rest should not scroll past. Never a warning: one behind a click is one nobody
read.
Page components has the rest - annotations, tabs, filter boxes, captions - with the Markdown for each and the case it is for.
Links¶
Use relative Markdown links between docs pages (../products/storage.md), so the build
verifies them. Link text describes the destination — never "click here".
Formatting¶
- Wrap prose at roughly 95 characters
- One sentence per line is fine in drafts; not required
- Code blocks always carry a language tag
- Tables for anything with more than two parallel facts
Terminology¶
| Use | Not |
|---|---|
| project | namespace (when addressing users), tenant |
| virtual machine, VM | instance |
| workload | app, service (when you mean the Kubernetes object) |
| GRN.CLOUD | GRN Cloud, Green Cloud, grn.cloud (in prose) |
oc |
kubectl — these docs and the GRN cluster repos use oc throughout |