Style guide
Rules for editing the notes in the more eyes project: Who Can Move Your Bitcoin? and What Can You Check About a Software Release?, and notes that apply the release note to one project, such as What Can You Check About an embit Release?, and Which Code Actually Runs?. They apply to every change, by any author. Check a change against this page before you commit it.
Section numbers in the rules, such as §1.1 and §8, refer to the custody note. Rules that differ for the release note are marked.
Readers
Each note has two readers.
- People making a decision. For the custody note, they are choosing how to hold bitcoin. For the release note, they are deciding what a download page is evidence of. Most are not technical. They read “Start here.”
- Technical reviewers. They read the full note.
Write “Start here” and any plain-language text for the first reader. Write the technical sections for the second reader, and keep them as clear as the content allows.
Content rules
- No names. Do not name products, companies, people, or specific incidents. Describe configurations, not providers. Release note exception: the release note, and each note that applies it to one project, names open-source projects, because these notes describe public release processes. They still do not name companies, people, or incidents. Where a record involves a person, name the role: the tagger, the commit author, a maintainer account. A key fingerprint is an artifact and can be given. Fallback note exception: Which Code Actually Runs? reads public incident records, so it names a product and its library, and it cites the publisher of each account in its References. In its text it uses roles: the maker, an independent analysis. It records each account as that party’s statement, and it leaves out loss figures and attribution. It states what each project’s public documents say, and it does not rank the projects.
- Conditions, not verdicts. State what a protocol does and what evidence a claim needs. Do not state that a product or design is safe or unsafe. Use only the result terms in §1.1.
- Cite mechanism claims. A statement about how a protocol or signature scheme works needs a public specification. Pin each source to a version in the References section. Where a web page cannot be pinned, record the date it was read.
- Label citations by what the source defines. A link label names what the specification actually specifies. Do not label an opcode as a recovery mechanism, or an output type as an escrow protocol.
- No frequency claims, in either direction. Do not claim how often something fails without cited incident evidence. Do not treat a record without known failures as evidence of soundness.
- Keep conditions with their claims. If a claim holds “only if” something, keep the claim and the condition in one sentence or one table cell. A reader must not be able to quote the claim without its condition.
Structure rules
- Do not renumber. Existing section and scenario numbers stay fixed, because reviewers cite them. Add new material inside an existing section, at the end of a list, or under an unnumbered heading.
- Version every change. Change the minor number when a claim, consequence, citation, or reader-facing text changes. Change the major number when numbering or structure changes in a way that breaks references. Typo-only edits do not change the version.
- Record every version. Add a changelog row that links the content commit. Tag the commit that contains the changelog row with the note’s tag prefix and the version, such as
release-v0.4. Sign the tag. Link the version in the changelog row to the tagged text. Update the version line in the README.
- Keep the filename. The filenames are
who-can-move-your-bitcoin.md and what-can-you-check-about-a-release.md. They stay fixed, so links keep working. Versions before 0.18 used what-a-custody-pitch-has-to-show.md; their tags keep that name, and a short file at that path links to the current one.
Each note has its own tag prefix, so that every tag names one note and one version.
- The unprefixed
v tags belong to the custody note only. Reviewers cite them, so they keep that form.
- A new note gets a short prefix that ends in
-v. Add it to this table in the same change that adds the note.
- Do not move or delete a tag. A correction gets a new version.
- A tag created after the fact says so in its message, with the date it was created.
- Adding a tag, or a changelog link to tagged text, does not change a note’s version.
Plain language
These rules follow Simplified Technical English (ASD-STE100) in part. They do not adopt its controlled dictionary. Apply them strictly in “Start here” and plain-language text. In the technical sections, apply them when you edit a passage.
- One word, one meaning. Use the same word for the same thing everywhere. Use the canonical terms below. Add new terms to §1.2.
- One idea per sentence. Aim for 20 words or fewer in an instruction and 25 or fewer in a description. Rule 6 under Content rules overrides this limit.
- No noun stacks. Do not put more than three nouns in a row. Say who does what to what.
- Active voice. Name the actor. Use the imperative for steps the reader does.
- Explain terms. In plain-language text, explain each technical term the first time you use it. In technical sections, link the term to §1.2 or explain it.
- Clear references. Do not start a sentence with “it” or “this” when the reader could be unsure what it refers to.
Canonical terms
| Use |
For |
Do not use for the same thing |
| holder |
The person whose bitcoin is at stake |
owner, customer, user (except “account holder” in Scenario H) |
| service |
An organization that holds a key, co-signs, runs signing infrastructure, or runs recovery |
provider, firm, vendor (plain-language text says “company” throughout and mentions once that the technical sections call it a “service”) |
| key |
A private key that authorizes signatures |
seed, share, backup (these are different things; see §1.2) |
| signer |
The component that uses a key to sign |
device, wallet (unless the device itself is meant) |
| spending path |
One complete way to satisfy an output’s spending conditions |
route, branch, leaf (a leaf is a Taproot term; see §1.2) |
| freeze |
Signer freeze or platform freeze, as defined in §1.2 |
lock, block (unless describing a timelock or a block in the chain) |
Release note terms
| Use |
For |
Do not use for the same thing |
| release file |
The file a person downloads |
artifact, download, package (unless a package in an archive is meant) |
| publisher |
The party that uploads the release file |
vendor, maintainer (unless the source says maintainer) |
| builder |
A person or machine that compiles the stated source and records the output hashes |
signer (the custody note uses “signer” for a component that holds a key), rebuilder (except for the Debian service, which uses that word) |
| attestation |
A signed statement about a file |
signature (a signature is one part of an attestation) |
| downloader |
The person who downloads and checks a release file |
user, customer |
| distributor |
A party that compiles another project’s source and publishes the result |
vendor, downstream |
| public, signed, rebuilt |
The three checks, as defined in the release note’s §1.2 |
reviewed (the note does not establish review), verified, reproducible (unless a source’s own wording is quoted) |
A term inside a quoted claim, such as “Multiple vendors or devices” in §6, keeps the claim’s wording.
Before you push
- Every BIP or other source cited in the text has a row in the References section, and every “Cited in” entry matches the sections that cite it.
- Every link in the Contents resolves to a heading.
- Every new external link loads.
- The changelog row, tag, and README version line match.
- Absolute links to this repository use
github.com/more-eyes/notes. Changing only a link’s address, with the same target, does not change a note’s version.