The house prose rules for the Arbitrum documentation portal, for anyone writing or reviewing a page. CONTRIBUTE.md holds the workflow: frontmatter, partials, variables, moving pages, the gates, opening a PR. This file holds the prose. The seven-item summary under Style conventions in that file is the short version; everything below is the long one, and the two do not disagree.
These rules are a standard for new content. A lot of existing pages predate them and are brought up to spec incrementally, not all at once. Nothing here is enforced by a gate unless this file says so, which means a reviewer applies it by reading.
Plain language means the reader finds what they need, understands it the first time, and can act on it. This section applies the ISO 24495-1 principles through the concrete rules of the Federal Plain Language Guidelines, plus two rules borrowed from ASD-STE100 Simplified Technical English.
Every rule below is testable in review.
| Rule | Correct | Incorrect |
|---|---|---|
| Address the reader as "you" | "You must fund the batch poster account." | "Users must ensure their batch poster account is funded." |
| Use active voice and name the actor | "The batch poster compresses transactions and posts them to the parent chain." | "Transactions are compressed and posted to the parent chain." |
| Use present tense | "The sequencer orders incoming transactions." | "The sequencer will order incoming transactions." |
| One idea per sentence | Two sentences of about 15 words each. | One sentence of 40 words with three clauses. |
| Use verbs, not nominalizations | "Configure the sequencer." | "Perform configuration of the sequencer." |
| Put the condition before the action | "If you run an AnyTrust chain, enable the DA server." | "Enable the DA server if you run an AnyTrust chain." |
| Use the imperative for steps | "Run pnpm build." |
"You should now proceed to run pnpm build." |
| State things positively | "Wait until the assertion is confirmed." | "Do not continue before the assertion is no longer unconfirmed." |
| Give concrete numbers | "The challenge period is 6.4 days." | "The challenge period takes a while." |
| Reserve must, should, and can | must = required, should = recommended, can = optional | "should" for a step the reader has no choice about |
Pick one name for each concept and use it for the whole page. Alternating between synonyms makes the reader ask whether you mean two different things.
| Concept | Pick one and keep it | Don't mix on one page |
|---|---|---|
| The chain your app runs on | child chain | L2, child chain, Arbitrum chain, rollup |
| The node that orders transactions | sequencer | sequencer, sequencing node, the orderer |
| The party that proposes assertions | proposer | proposer, staker, validator |
Expand every acronym on first use. Link that first mention to the glossary when an entry exists for the term, as described under Linking a term to the glossary.
| Don't write | Write |
|---|---|
| utilize, leverage | use |
| in order to | to |
| prior to, subsequent to | before, after |
| facilitate | help |
| terminate | end |
| sufficient | enough |
| additional | more |
| approximately | about |
| commence, initiate | start |
| in the event that | if |
| at this point in time | now |
| e.g., i.e., etc. | for example, that is, and so on |
Delete these openers and keep the sentence that follows: "It is important to note that", "Please note that", "As previously mentioned", "In the context of", "It should be pointed out that".
Never write "simply", "just", "easy", "obvious", or "of course". When the step does not work, these words tell the reader the fault is theirs.
- One topic per paragraph, five lines at most.
- Convert any sentence with three or more conditions into a bulleted list or a table.
- Lead each section with the outcome, then the detail.
- Write headings a reader can scan to find their task.
Glossary terms live in content/glossary/, one .mdx file per entry, each with an id in its
frontmatter. In a page, wrap the term in <Term> and give it that id:
Save the console output so you can use it with your <Term id="dapp">decentralized app</Term>.The component renders the linked text with the glossary definition in a hover popover. The id is the
entry's id, not the words on the page, so the visible text is yours to write: id="dapp" above
carries the wording the terminology table asks for.
Four rules:
- Once per file, on the first mention. Leave every later mention of the same term as plain text. A second popover on the same term tells the reader nothing new and turns the page into a field of links.
- Only for terms that have an entry.
pnpm references:checkis a blocking CI gate and fails on an id with no matching file, so a typo is caught rather than silently dropped. (pnpm builditself runs onlycheck-links; the other gates run in CI and by hand.) - Add the entry rather than skipping the link when a term deserves one and has none. A new file
under
content/glossary/needs onlyidandtitlein its frontmatter, plus the definition as its body. - Inside a partial, link the partial's first mention. A
<Term>works in a partial: the include is spliced into the page at build time, so the component renders in the page. A partial cannot know what its including pages already link, so apply the once-per-file rule to the partial itself.
<ReferenceList> renders the whole glossary and belongs only on the glossary index page.
One spelling, one capitalization, across the whole site.
| Term | Correct | Incorrect |
|---|---|---|
| JavaScript | JavaScript | js, javascript, Javascript |
| app | first mention on page: decentralized app later mentions: app |
dapp, dApp |
| Smart contract | smart contract, contract | smartcontract |
| Cross-chain | cross-chain | cross chain, crosschain |
| Allowlist / denylist | allowlist, denylist | whitelist, blacklist |
| ERC-XX (ERC-20, ERC-721, …) | ERC-20, ERC-721, ERC-1155 | ERC20, erc721, … |
| Sequencer Coordination Manager (unsettled, see the note below) | upstream: Sequencer Coordination Manager (SQM) | see the note below |
| AnyTrust | AnyTrust | anytrust, Anytrust |
| Ethereum currency | ETH, Ether, ether | eth, Eth, ETH |
| onchain | onchain | on-chain, on chain |
| Arbitrum chains | "Your Arbitrum chain" | "L3 Orbit chain", "blockchain" |
| Challenge period | 6.4 days to challenge an assertion | confirmation period (a different term) |
| Bond | bond, bonded funds for proposing | stake, staked funds |
| Rollup | Rollup | rollup |
The Sequencer Coordination Manager row is unsettled, so do not act on it yet. The Correct column
records upstream's wording verbatim, (SQM) included, which is upstream's initialism and not an
abbreviation of either expansion. This repo's pages mostly say "Coordinator Manager", one page is
filed at run-sequencer-coordination-manager.mdx while its own title says Coordinator, and Nitro's
flag family is node.seq-coordinator.*. Naming the tool is the docs owner's call and is still open,
so leave both spellings alone until it is decided.
- Document types. Which of
how-to,concept,quickstart,tutorial,reference,troubleshootingorfaqa page is, and what each one owes the reader, is in CONTRIBUTE.md. The enum itself is enforced by the frontmatter schema inlib/page-schema.ts, throughpnpm frontmatter:checkand the build. - Callout syntax. Use
<Callout type="…">, withtypeset toinfo,warn,error,ideaorsuccess. Docusaurus:::directives do not render here, andpnpm content:lintruledocusaurus-directiveis a blocking gate that fails on one. - Diagrams. Prefer SVG for scalable, editable diagrams; use PNG when SVG is unsuitable. Concept
diagrams follow the
arbitrum-brand-svg-diagramsskill under.claude/skills/, which covers the palette, asset location, and an Excalidraw editing workflow.
This file is the live copy of the Offchain Labs pattern guide.