Writing these pages

This page is the house style for hpr-sim’s documentation. It is for anyone who writes or edits a page of this site, a model page, or a doc comment. It applies to every new page and to every page a change touches. Older pages move to it as they are edited, not all at once.

The aim is simple: a hobby rocketeer who knows some physics and some code, but not this project, reads a page once and knows what it says and how far to trust it.

The rules

1. Bottom line first. The first sentence of a page, a section or a paragraph says what it concludes. The detail and the reasoning come after.
2. One idea a sentence. Aim for about 20 words a sentence on average. A sentence over 25 words is flagged for a second look; it is not forbidden.
3. Short paragraphs. Five sentences at most.
4. Numbers carry their meaning. Every number has a unit, and says what it is compared with: “apogee 1.2% above RocketPy’s”, not “1.2% error”.
5. One fact, one precision. The same fact is written with the same precision everywhere it appears. If one page gives the real-flight apogee error as 6.04%, no other page rounds it to 6%.
6. Labels are links. An internal label, such as a milestone or a decision record, is a link with a few words of meaning, never bare. The site’s checks enforce this one (the documentation site decision record).
7. Words before equations. Say in words what an equation does, give the equation, then work an example with real numbers.
8. Honesty comes first. These standing rules still apply: a page opens by saying how far to trust it; anything unvalidated says so in its first paragraph; example code runs in CI; and an accuracy number comes from the committed validation report (Checking a claim).

The FusionSpace rules

hpr-sim is a FusionSpace project (FS · SW · TOOL 005), and its pages also follow the product system’s writing rules and number rules (the product system decision record). They don’t conflict with the rules above; they add these:

• US English: color, center, meter, catalog, license, analyze, gray. A product or command name keeps the spelling it shipped with, and a quotation or a source’s title keeps its own.

• No em dashes. Use a colon, a comma or a period. An en dash only in ranges: 5,100–5,500 ft.

• Both are checked. cargo xtask spelling flags the UK spelling of eight words, whose US forms are center, meter, catalog, license, color, analyze, behavior and modeling, and names the US word to write; it flags every em dash, in the pages and their code blocks, the crates, xtask and the schema alike (since M0.6d3). Other UK spellings (labelled, neighbours, maths, grey) are not checked yet. It reads the pages, the README, the scripts, the crates, xtask and the schema: a page’s prose, each code block as its language reads (a rust block’s comments and strings, a text block whole), and a source file’s comments and strings. It skips addresses, the frozen decision records and its own word list.

• Names are checked too (since M0.6e): every name in the code, a string that is one bare key such as "center_x", and each name in the writing (in backticks, joined by _, in a format string). It reports centre_of_pressure_m as “call it center_of_pressure_m”. A quotation, a source’s title, a name that keeps its spelling, or a key that files saved before the rename or another program’s format hold goes on the check’s short list of exceptions, which it counts on every run. --fix replaces words but not names: a renamed name that is saved to a file keeps its old key as a serde alias, which hpr reads and never writes. An em dash needs its sentence rewritten. CI runs the check in the site step.

• How far to trust it, in a fixed shape, on every result someone might fly on: what kind of figure it is (estimate, measurement, copied value); what it was checked against, with numbers; what to rely on instead when it matters. Never a go/no-go verdict.

• Signal words are those of ANSI Z535, the US safety-sign standard, and no others: DANGER, WARNING, CAUTION, NOTICE, NOTE, each as a panel above the text with the hazard, the consequence and how to avoid it.

• Numbers and dates:

  rule	write
  a space before the unit, except degrees and percent	21.5 °C, 45°, 7.0%
  commas in groups of three in prose; none in terminal output or anything copied	5,104 ft; 1280 ft
  precision that matches what is known	5,104 ft from a barometer, not 5,103.87 ft
  dates in prose; in tables and files	October 4, 2026; 2026-10-04

• FusionSpace is one word.

Older pages move to these rules as they are edited. M0.6, the product system milestone, adds a check for the first two.

Four kinds of page

Pages follow Diátaxis, a common way to sort documentation by what the reader is doing. Each page is one kind; a page that mixes them is split when it is next touched.

Measured, not gated

Readability will be measured, not used to fail a build. A planned cargo xtask report will print, for each page, the average sentence length, the share of sentences over 25 words, and how many internal labels it holds per 100 words. The report will show where to look; a person decides what to change.

One hard check is planned, and may land in the bookkeeping clean-up (M0.5 milestone). A model page’s In short box, the bulleted summary that opens it (what it models, its sources, how well it is validated, what it leaves out), will hold at most about 150 words and five bullets.

The targets for user pages, measured at Neer’s next check-in: at most 20 words a sentence on average, and fewer than 10% of sentences over 25 words.

Where this comes from

The rules follow the UK Government Digital Service’s style guide, and the sentence-length checks that Datadog and GitLab run with the Vale linter. The page kinds are Daniele Procida’s Diátaxis framework. The decision to adopt them is in the check-in decision record.