Content guidelines
How this guide is written: who it is for, the rules the build enforces, and the vocabulary that is not negotiable.
One voice across more than a hundred pages, written by different people. These rules make that possible.
Who you are writing for
Somebody building a BSV product: a designer drawing it, a researcher finding out whether it works, a founder deciding what it should be, or a developer doing some of each. They are competent, busy, and probably arriving from a search result rather than the first page.
They are not here to be convinced about bitcoin. Assume somebody who has already decided to build and now needs to know what to draw.
Do
Answer the page's question in its first two sentences, and link every term the page relies on rather than assuming the reader came from the page before.
Say the useful thing first
The reader wants the answer, not the build-up. Lead with what changes on the screen, then explain why, if the why matters.
Don't
Open with a paragraph about how bitcoin is changing the world. Nobody reading a page about send screens needs it.
Do
Start a section with the conclusion, in one sentence, and let the rest support it.
Be short
The guide is long because the subject is. Individual pages should not be.
Do
Cut the sentence that restates the previous sentence.
Do
Use ordinary words. "Use", not "utilise". "About", not "approximately".
Don't
Pad a thin page to look thorough. A four-hundred-word page that answers the question beats two thousand that circle it.
Give rules, not opinions
Every page's Do and Don't items become its checklist, which somebody will tick off while they work. So each one has to be actionable on its own, away from the paragraph above it.
Each rule also gets a permanent link made from its wording, so rewording a rule breaks every citation of it. Get the wording right first.
Do
Write a rule that can be followed or broken: "Show the recipient larger than the amount on a review screen."
Don't
Write a rule that cannot be checked: "Consider the user's needs when designing."
Be honest about what is settled
Some of this guide is specified in a proposal. Some is what good products do. Some is a reasonable guess.
Do
Say which. "The standard requires", "most wallets do", and "we suggest" are three different claims and the reader can tell them apart.
Do
List what you worked from in the page's sources: front matter.
Vocabulary
These are enforced. npm run check fails on the banned terms.
| Write this | Not this |
|---|---|
| Recovery words | Seed phrase, mnemonic |
| Handle | Wallet address, for a handle |
| Pass | Credential, for an identity certificate |
| Connect | Link, integrate |
| Guide, section, page | Docs, chapter, entry |
| Carried over | Legacy, outdated |
| Web 3 Native | web3 |
| Metanet, for the capability set | Metanet, as a product or a network you join |
| Satoshis, sats | Long decimal BSV amounts |
| bitcoin, meaning BSV | "bitcoin" used to mean some other chain |
| Another chain, other networks | BTC, outside a comparison page or an explainer |
Legacy compatibility keeps its name because it describes older wallet formats, not this guide's pages.
A page that must break a ban to tell people not to use a term lists it in allows: in the front matter. This page does.
Metanet and Web 3 Native describe the same territory and are not synonyms. Web 3 Native is the user's side: an app you connect your own wallet to. Metanet is the protocol's side, and names a specific combination: proof of work, the unspent output set as a database, and restored script. Use whichever side you are writing about, and define neither twice; the glossary holds both.
Do
Write satoshi amounts with grouped digits and the unit: "12,500 sats", not "12500 sats" or "0.000125 BSV".
Do
In interface copy, name the network "Bitcoin SV" or "BSV". In prose, "bitcoin" alone means BSV.
Both follow Amounts and units: see Use satoshis and Naming the network.
Examples and the cast
Examples reuse one cast, fictional apart from the wallet, so a reader who meets Anna on one page recognises her on the next.
| Role | Use |
|---|---|
| The main user | Anna Keller, handle anna@example.com, wallet Bitcoin SV Wallet |
| Other people | David, Maya, Tom |
| Products and places | The Satoshi Vision, Example Tickets, Scout, Pixel Arcade, Corner Café |
| Exchange rate | 2,000 sats to £1, so 20 sats is about 1p and 10,000 sats is about £5 |
Handles are written without a leading @, as in anna@example.com, unless the page is about a handle scheme that requires one.
Do
Reuse the guide's cast and handle format. Do not invent new names for a single example.
Cite a standard, do not name things after it
A proposal number identifies a document. It is not the name of the thing the document specifies.
| Form | Where it belongs |
|---|---|
| BRC-100 | A citation, or the sources: list |
| Wallet Application Interface | Prose |
| Connect wallet | A string in an interface |
So: "the recommended peer-to-peer payment flow (BRC-29)", never "a BRC-29 payment". A wallet that implements the connection standard is a connected wallet, not a "BRC-100 wallet".
Don't
Make the reader look up a number to learn a word you could have told them.
Punctuation and formatting
Don't
Use an em dash. The build rejects them. Use a comma, a full stop, or brackets, and the sentence usually improves.
Do
Use sentence case in headings. "Backing up a wallet", not "Backing Up A Wallet".
Do
Put a link on the words that describe the destination, never on "here" or "this link".
Show it
A screen is easier to understand than a paragraph about a screen.
If the image does not exist yet, leave a placeholder with a prompt rather than describing it in prose. See Formatting for the syntax and Illustration guidelines for what to make.
What this guide does not do
It describes the design consequences of how bitcoin works, and in this guide bitcoin means BSV. It is a reference, not a campaign.
The boundary holds in both directions: no campaigning for this system, and no sneering at any other. Four pages carry a comparison, because a reader needs one to avoid losing money or shipping a broken script: Why BSV is different, Legacy compatibility, the glossary's table of terms that do not apply, and Published research.
Outside those four pages there is one exception: a short panel where a belief from another chain would cost somebody money or ship a script that enforces nothing. Put it where the reader will hit the problem:
:::fact[Commonly misunderstood: waiting for confirmations]
On BTC, replace-by-fee means a transaction you have seen can still be
swapped for a conflicting one, so a merchant waits for a block.
BSV has no replace-by-fee, so the wait buys far less than it does there.
:::Use it only where the reader would otherwise lose money or ship something broken. Never for emphasis.
Name the chain in the panel, because vagueness is what lets the belief survive. Any page carrying one declares allows: [BTC] in its front matter, so the check still catches a mention nobody meant to make.
Do
Write a misconception panel in three parts: what the reader probably believes, why it is false on BSV, and what goes wrong silently if they act on it.
Everywhere else, describe what this system does and leave the others out of it.
Don't
Write a sentence whose job is to score a point. It costs the reader's trust and it will be edited out.
Related
Written from: DESIGN.md, scripts/check-content.ts.
Checklist
The rules on this page, in a form you can work through.
19 rules