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. These are docs. If a capability is limited, say so — that is more useful than a claim the reader will disprove in ten minutes.
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 the flow works; a drawn one is a lie with extra steps. Redact tokens, keys, internal hostnames and customer identifiers before committing.
Admonitions¶
Use them sparingly — a page of warnings reads as no warnings at all.
| 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 |
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 |