A background job finds the place of each node that advertises a location (Villeray, Montréal; a village; a peak near its summit). The map tiles give the first answer offline; Nominatim corrects it when online (place_source, default tiles then Nominatim; nominatim_url). Places are stored in the new node_places table, a typed place in places.json wins over a found one. Co-Authored-By: Claude Haiku 5.5 <noreply@anthropic.com>
361 lines
22 KiB
Markdown
361 lines
22 KiB
Markdown
# How we write
|
||
|
||
MeshTerm's technical text is written in **ASD-STE100 Simplified Technical English** (STE),
|
||
with Canadian spelling. This page gives the rules, the few rules that we bend, and the
|
||
glossary. Use it when you write a docstring, a comment, a document, a guide, or a
|
||
changelog entry.
|
||
|
||
STE is a controlled language. It started in the aerospace industry, where a maintenance
|
||
manual must have only one meaning for each reader. It has a set of writing rules and a
|
||
dictionary of approved words. Its purpose is text that a reader understands quickly and
|
||
correctly, also when English is not the first language of that reader.
|
||
|
||
## What is written in STE
|
||
|
||
| Written in STE | Not written in STE |
|
||
| --- | --- |
|
||
| Docstrings and code comments, in `meshterm/`, `tests/`, `scripts/`, and `packaging/` | The licences, `NOTICE`, and other legal text |
|
||
| The README, `CONTRIBUTING.md`, `SECURITY.md`, and the documents in `docs/` | The written pages in `meshterm/assets/pages/` (About MeshTerm, About the author, Discord, Support). These are the author's own words |
|
||
| The guides, the CLI manual, and the device manuals | `CODE_OF_CONDUCT.md`, which is a standard text |
|
||
| The changelog | The one-line description of MeshTerm (the package docstring, `pyproject.toml`, the CLI help). It is fixed text |
|
||
| | Quoted text: error messages, log lines, command output, UX strings, and the words of other persons |
|
||
| | Identifiers, file names, commands, and code |
|
||
|
||
UX strings (the text on the screens) follow the UX standards in `CLAUDE.md`.
|
||
|
||
## The rules
|
||
|
||
### Words
|
||
|
||
- Use simple, common words. Use one word for one meaning, and one meaning for one word.
|
||
When the glossary gives a word for a concept, use that word each time.
|
||
- Use a word as only one part of speech. "Record" is a noun ("a stored record"). For the
|
||
verb, use "store".
|
||
- **Technical names** are permitted: identifiers, file names, commands, product names,
|
||
standards, and the terms in the glossary below. A technical name can end in "-ing"
|
||
("the setting", "the padding", "a heading", "the encoding").
|
||
- **Technical verbs** are permitted: verbs for a computer process, such as compile,
|
||
render, parse, decode, encode, cache, push, pop, flash, boot, install, and log in.
|
||
- Do not use Latin abbreviations. Write "for example" for "e.g.", "that is" for "i.e.",
|
||
and "and other ..." for "etc.".
|
||
- Do not use contractions. Write "do not", not "don't". Write "it is", not "it's".
|
||
- Use Canadian spelling: "colour", "behaviour", "centre", "grey", "licence" (the noun),
|
||
"metre" (the unit), "organize". A "meter" is an instrument (the `meter` widget). Keep
|
||
identifiers and quoted text as they are (`color_map`, the "Apache License").
|
||
- Name the actor of an action: "MeshTerm sends", "the function returns", "the screen
|
||
draws". Use "we" only for a decision of the project ("We do not ... because ...").
|
||
- The possessive "'s" is permitted ("a handheld's own screen", "M5Stack's Cardputer").
|
||
Use "of" when the possessor is long. Do not make an awkward "of" phrase only to avoid
|
||
"'s" ("the own screen of a handheld" is wrong).
|
||
|
||
### Verbs
|
||
|
||
- Use these verb forms: the infinitive ("to start"), the imperative ("Start"), the simple
|
||
present ("starts"), the simple past ("started"), and the future ("will start").
|
||
- Use the past participle only as an adjective ("the changed file") or after a form of
|
||
"to be" ("the file is changed").
|
||
- Do not use the "-ing" form as a verb. Write "before you start the app", not "before
|
||
starting the app". Write "while the map draws", not "while drawing".
|
||
- Use the active voice. In a description, use the passive voice only when the agent is
|
||
unknown or not important.
|
||
- Use a verb for an action, not a noun. Write "examine the log", not "do an examination
|
||
of the log".
|
||
- Use "must" for an obligation, "can" for a possibility or an ability, and "will" for the
|
||
future.
|
||
|
||
### Sentences and paragraphs
|
||
|
||
- An instruction has a maximum of 20 words. A description has a maximum of 25 words.
|
||
An identifier, a number, or a file path counts as one word.
|
||
- Write one topic in each sentence.
|
||
- Do not omit words to make a sentence shorter. Keep "a", "the", "that", and the verbs.
|
||
- Use a vertical list for steps, options, and conditions.
|
||
- Use connecting words between related sentences: "then", "but", "because", "if", "when",
|
||
"also", "after", "before", "thus".
|
||
- Start a paragraph with the most important information. A paragraph has a maximum of six
|
||
sentences.
|
||
|
||
### Instructions and safety
|
||
|
||
- Write an instruction in the imperative: "Run the tests."
|
||
- If a condition comes first, put a comma after it: "If the test fails, examine the log."
|
||
- Put a safety instruction before the step that has the risk. **WARNING** is for a risk
|
||
of injury. **CAUTION** is for a risk of damage to equipment or a loss of data. Start
|
||
with the instruction, then give the risk.
|
||
|
||
### Punctuation
|
||
|
||
- Do not use semicolons. Write two sentences.
|
||
- Do not use a dash (`—`) to join two parts of a sentence. Use a period, a comma, a colon,
|
||
or parentheses.
|
||
- Use a colon before a list, an example, a quotation, or code.
|
||
- Use parentheses only for a short reference, an example, a key name, a unit, or a label.
|
||
|
||
### Pronouns
|
||
|
||
- Use "this" and "these" with a noun: "this change", not "this" alone.
|
||
- Use "it" only when the noun that "it" refers to is clear and near.
|
||
|
||
## The rules that we bend
|
||
|
||
STE is our default, and we do not drift from it. But a rule can bend when the STE form is
|
||
less clear or less exact than the normal form. These are the permitted bends:
|
||
|
||
1. **Modal verbs for uncertainty.** "Should", "may", "might", and "could" are permitted
|
||
when they show that something is not known ("the terminal may not have the font").
|
||
For a known possibility, use "can". For an instruction, use "must" or the imperative.
|
||
2. **Perfect and progressive tenses.** "The device has closed the connection" and "a
|
||
flood is in progress" are permitted when they are more exact than the simple tense.
|
||
3. **Longer sentences.** A description can be longer than 25 words when a division
|
||
breaks the connection in an argument. A design rationale ("we do X, because Y, and Z
|
||
is the result") is often this type of sentence.
|
||
4. **Counterfactual "would".** Code often has a reason in the form "if we did X, Y would
|
||
occur". First, try the simple tense: "If the hint is cut, the cut removes Esc." When
|
||
that form is not clear, "would" is permitted.
|
||
5. **Technical verbs and terms of software.** "Check" (code tests a condition), "call",
|
||
"return", "push", "pop", "cache", "parse", "render", and the other terms of the
|
||
glossary are permitted. STE has no dictionary for software, so the glossary is ours.
|
||
6. **Phrases where a phrase is normal.** A heading, a table cell, a list item, the first
|
||
line of a docstring, and a short comment can be a phrase instead of a sentence.
|
||
|
||
Use a bend only when it helps the reader. In all other cases, use the STE rule.
|
||
|
||
## Docstrings and comments
|
||
|
||
### Docstrings
|
||
|
||
- The first line is a summary. It is a sentence or a noun phrase, and it ends with a
|
||
period. A noun phrase is good for a function that returns a thing ("The glyph that a
|
||
command row starts with."). A sentence in the simple present or the imperative is good
|
||
for a function that does a thing ("Clamp the highlight to the list.").
|
||
- After the first line, explain what the code does, then why. The reason is the most
|
||
important part of a docstring, because the code cannot show it. Keep each reason.
|
||
- Keep the Google sections (`Args:`, `Returns:`, `Raises:`, `Yields:`). Write the
|
||
entries in STE.
|
||
- Keep cross-references (`:func:`, `:class:`, `:data:`, `:mod:`). Write "Refer to
|
||
:func:`x`" or "(refer to :func:`x`)" instead of "see".
|
||
- Write an identifier in code font: ``like_this``. Keep quoted UX strings exactly, in
|
||
code font or in quotation marks.
|
||
- Do not use capitals or italics for emphasis. Write "the only renderer", not "THE
|
||
renderer". Use italics only for a term at its definition. Bold is permitted for a term
|
||
at its definition, and for the one most important fact of a paragraph. Use it rarely.
|
||
- Write the history of a decision in the simple past, and keep it short: "The hint once
|
||
had a separate Back row. We removed it, because Esc does the same thing."
|
||
- Keep a quotation of a decision exactly, with its name and date ("JP, 2026-09-30: ...").
|
||
|
||
### Comments
|
||
|
||
- A comment that explains is written in STE sentences. A short comment can be a phrase
|
||
("Clamp at both ends.").
|
||
- Keep the tool part of a tool comment exactly as it is: `noqa: BLE001`,
|
||
`type: ignore[attr-defined]`, `pragma: no cover`, `fmt: off`, and the SPDX line. The
|
||
explanation after the tool part is prose: write it in STE
|
||
(`# noqa: BLE001 - an optional read. Its absence is acceptable.`).
|
||
- Write a quoted UX label in code font or in double quotation marks, never in italics.
|
||
- Keep the `#:` mark of an attribute comment. Write its text in STE.
|
||
- Keep the layout of a diagram, a table, or an example in a comment. Change only its
|
||
words.
|
||
- Do not change commented-out code.
|
||
|
||
## Glossary
|
||
|
||
One word for one concept. The words in this glossary are technical names in MeshTerm.
|
||
Use them with this meaning only. Use the words in the "Not" column only in identifiers
|
||
and in quoted text.
|
||
|
||
### The mesh
|
||
|
||
| Word | Meaning | Not |
|
||
| --- | --- | --- |
|
||
| node | Any device on the mesh: a radio that transmits packets. The types are companion, repeater, room server, and sensor | station |
|
||
| contact | A node that your device knows. It is **discovered** (heard, not added) or **added** (in the contact list, and you can send messages to it). Each contact is a node. Not each node is a contact | |
|
||
| our node | The node of the companion that MeshTerm is connected to. On the screen, it is "you" (★) | own node, self node, local node |
|
||
| companion | A node that a program (such as MeshTerm) controls through USB, Bluetooth, or TCP | |
|
||
| managed node | A node whose admin password MeshTerm stores, so that the user can log in to it with no prompt. It has the `🔑` mark | remembered admin, administered node |
|
||
| device | The companion that MeshTerm is connected to (the `Device` class) | radio (for the companion) |
|
||
| handheld | A small computer that runs MeshTerm on its own screen: the PicoCalc, the Cardputer Zero, or the uConsole | device (for the computer), on-device |
|
||
| radio | The LoRa radio in a node | |
|
||
| Bluetooth adapter | The Bluetooth hardware of the computer that runs MeshTerm | Bluetooth radio |
|
||
| heard | Received over the radio from a node ("last heard", "first heard") | seen |
|
||
| key | The full value of a public key or a channel secret | |
|
||
| hash | The short identifier that comes from a key: the first one to three bytes of a public key (the path hash mode sets the number), a channel hash, or one hop in a path | short key |
|
||
| key prefix | The first bytes of a public key, longer than a hash: six bytes (12 hex digits) for the address of a direct message and the id of a node in stored history, or four bytes for the author of a room post. It is a truncated key, never a hash | hash (for a key prefix) |
|
||
| path | An ordered list of hops that you write or force (`a1,3d,…`) | |
|
||
| route | The sequence of nodes that a trace went through or will go through | |
|
||
| hop | One node in a path or a route | |
|
||
| via | The prefix for the relay chain of a packet or a message | |
|
||
| location | The coordinates (latitude and longitude) that a node advertises | coordinates (alone) |
|
||
| place | The named area nearest the location of a node: a neighbourhood, a village, a town, or a peak. It has a fine part and a coarse part (`Villeray, Montréal`) | location name, locality |
|
||
| region | A named area for which a repeater relays floods (`region put yul`). Shown without `#` | |
|
||
| scope | The region to which a flood is limited | |
|
||
| unscoped | A flood that each repeater relays when it permits the wildcard `*` | |
|
||
| flood | A packet that each repeater that hears it transmits again | |
|
||
| advert | A packet in which a node broadcasts its name, key, and position | advertisement |
|
||
| BLE advertisement | The Bluetooth LE packet in which a peripheral broadcasts its name. It is not a MeshCore advert | BLE advert |
|
||
| room | The message board of a room server. You join a room, read it, and post to it | |
|
||
| post | A message on the board of a room | |
|
||
| packet | One radio transmission | frame (for radio data) |
|
||
| protocol frame | One unit of the companion protocol on USB, Bluetooth, or TCP: a command, a reply, or a push from the companion. In code that handles only this protocol, "frame" alone is permitted | packet (for this) |
|
||
| message | A text message, direct or on a channel | |
|
||
| sender time | The time that a message or an advert carries, from the clock of the node that sent it. It is a claim, and a node with a wrong clock makes it false | timestamp (alone) |
|
||
| arrival time | Our clock when MeshTerm got a received message from the companion (`received_at`) | receive time |
|
||
| clock offset | The sender time minus the arrival time. A positive offset is a clock ahead of ours. The offset of a node is the median of its three newest clock samples | skew, drift (for this) |
|
||
| clock sample | One packet that gives a clock offset: an advert, a direct message, or a channel message, with its sender time and our time | |
|
||
| corrected time | The arrival time that the screen shows in place of a wrong sender time, with the `?` mark | |
|
||
| send | MeshTerm gives a message, a packet, or a command to the device | emit |
|
||
| transmit | A radio puts a packet on the air | |
|
||
| broadcast | Transmit to all nodes, with no destination | |
|
||
| relay | A repeater transmits a packet again | |
|
||
| receive | Data from the device arrives at MeshTerm | |
|
||
|
||
### Settings
|
||
|
||
| Word | Meaning | Not |
|
||
| --- | --- | --- |
|
||
| setting | A value of the radio. The device keeps it. You edit it on Device config | |
|
||
| preference | A value of MeshTerm's own behaviour, in `preferences.toml`. You edit it on the Preferences page | option (for this) |
|
||
| config | The setup of the machine: paths and device profiles, in `config.toml` | configuration file |
|
||
|
||
### The screen
|
||
|
||
| Word | Meaning | Not |
|
||
| --- | --- | --- |
|
||
| user | The person who uses MeshTerm | reader, operator |
|
||
| screen | A full-frame place in the app that the user is in: a menu, the map, a list, an editor | view |
|
||
| dialog | A floating box that informs, confirms, or asks. When the question is answered, it closes | popup, pop-up |
|
||
| prompt | A dialog or a line that asks for typed text | |
|
||
| page | All the content of a screen, which can be taller than the terminal. Also a written page | |
|
||
| frame | The full image that MeshTerm composes for the terminal in one paint: the title bar, the panel, the body, and the footer | |
|
||
| video frame | One image of a video, such as the demo video that `scripts/video.py` makes | frame (for this) |
|
||
| paint | One full update of the terminal | redraw, repaint, refresh (for the terminal) |
|
||
| animation step | One image of an animation (a spinner) | frame (for this) |
|
||
| panel | The box with a border around the body of a screen | panel (for the hardware) |
|
||
| display | The physical screen of a handheld | panel |
|
||
| window | An operating-system window: a terminal window, or the window of the emulator. A "time window" is a span of time | |
|
||
| terminal | The terminal program or the console that shows MeshTerm | |
|
||
| row | One item of a list or a table on the screen. A row can have more than one line | |
|
||
| line | One line of text | |
|
||
| cell | One character position on the terminal. Widths are in cells | column (for width) |
|
||
| column | A vertical part of a table | |
|
||
| lane | An aligned column in the rows of a list (`Lane`) | |
|
||
| F-key lane | The row of F-key chips at the bottom of a handheld screen | |
|
||
| graph lane | The horizontal track of one route in the route graph. In `pathgraph.py`, which has only this meaning, "lane" alone is permitted | |
|
||
| marker | The glyph of a node on the map or on the route graph | |
|
||
| raster | The rendered picture of the map, before MeshTerm draws it in the frame | frame (for this) |
|
||
| legend | The list of node types and their glyphs under a graph or a map | key (for this) |
|
||
| chip | A label in reverse video: a button, an F-key label, or one hop of a path line | |
|
||
| hint | The line of key hints in the footer, or in the border of a dialog | |
|
||
| atom | One item of a hint or a status line, between `·` marks | |
|
||
| highlight | The row that `❯` points to | cursor (for the row) |
|
||
| pointer | The `❯` glyph that marks the highlight | cursor (for the glyph) |
|
||
| screen on the stack | One entry of the navigation stack: a screen or a dialog that is pushed | frame, stack frame (for this) |
|
||
| insertion slot | The place in the path composer where the next hop goes | cursor (for this) |
|
||
| glyph | A symbol that a font draws | |
|
||
| character | One code point in a text | |
|
||
| icon | The emoji or glyph at the start of a menu row | |
|
||
| mark | A status glyph: `✓`, `✗`, `●`, `○`, `⚠` | |
|
||
| colour | Any colour | color (in text) |
|
||
| hue | The colour of a node, which comes from its key | |
|
||
| light | Show the hash bytes of a key in the hue of its node (`highlighted_hash`) | highlight (for this) |
|
||
| style | A named style of the theme | |
|
||
| keyboard key | A key on the keyboard. Write the key name when you can ("the Esc key", "F4") | key (alone) |
|
||
| setting key, preference key | The name of a setting (`tx`, `radio`) or of a preference in a command or a file. A dictionary key or a JSON key also has its qualifier | key (alone) |
|
||
| key press | One press of a keyboard key | keystroke |
|
||
| visible | On the screen | in view |
|
||
| viewport | The part of a page, or of the map, that the screen shows. A page that is taller than its viewport scrolls | view, window (for this) |
|
||
| list window | The visible rows of a list that scrolls inside a screen (`ListWindow`) | window (alone) |
|
||
| locate | Open the map on a node, or move the map to our node (the `locate` action, ^L) | find (for this) |
|
||
|
||
### The program
|
||
|
||
| Word | Meaning | Not |
|
||
| --- | --- | --- |
|
||
| call | Code calls a function | invoke |
|
||
| caller | The code that calls a function | |
|
||
| return | A function gives its result to the caller | hand back, give back |
|
||
| run | Start and do a tool, a command, a test, or a process. As a noun, one execution of a command or of MeshTerm | invocation |
|
||
| select | The user chooses a row, a value, or an action | pick |
|
||
| start, stop | Begin or end a process, a service, or a task | launch, kick off, halt |
|
||
| open, close | Begin or end a screen, a dialog, a file, or a connection | |
|
||
| leave | The user goes from a screen back to the screen below it. Also, the user leaves a room: MeshTerm forgets it, because a member cannot resign | |
|
||
| quit | The user leaves the app | |
|
||
| exit | A process ends. Its result is the exit status | |
|
||
| draw | Put text or glyphs on the frame | |
|
||
| render | Change data into text, ANSI bytes, or a document | |
|
||
| show | Make information visible to the user | display (as a verb) |
|
||
| print | Write to stdout or stderr | emit |
|
||
| read, write | Get bytes from, or put bytes into, a file, a stream, or the device | load, fetch |
|
||
| store | Keep data in the database or a file for later use | persist, record (verb) |
|
||
| save | Do an explicit save: the user's Save, or the device's save command | |
|
||
| record | One stored data item | |
|
||
| delete | Remove stored data permanently | purge (except the Purge feature) |
|
||
| secret | A value that unlocks something: a password, a channel secret, a pairing PIN, a private key. No log keeps one: it is hidden as `<secret>` | credential (except in a name) |
|
||
| hide (a secret) | Replace a secret with `<secret>` in a log or in the run log | redact, scrub |
|
||
| personal detail | A value that identifies the user or the equipment of the user, but is not a secret: the account name in a home folder, the address of a radio, the address of a host | PII, private data |
|
||
| mask | Replace most characters of a personal detail, and keep its first and last characters: `j*********u`, `DA:xx:xx:xx:7C:7C` | redact, scrub, obfuscate |
|
||
| anonymize | Mask each personal detail in a text: the `anonymize` preference does it to the log and the diagnostics | |
|
||
| remove | Take an item out of a collection or a text | drop, strip |
|
||
| clear | Make empty | |
|
||
| download | Get a file from the network | fetch |
|
||
| device file | A file in `/dev` (`/dev/spidev0.0`, `/dev/ttyUSB0`) | node (for a device file) |
|
||
| check | Code tests a condition | |
|
||
| make sure | Code or a person causes a condition to be true | ensure |
|
||
| examine | Look at something carefully | inspect |
|
||
| probe | Ask a terminal or hardware what it can do | |
|
||
| cache | Keep a result to use it again | memo, memoize |
|
||
| refresh | Get a new value for cached data | |
|
||
| error | An exception, or a message about a problem | |
|
||
| failure | An operation that did not complete | |
|
||
| bug | A fault in the code | |
|
||
|
||
### Words to replace
|
||
|
||
| Do not use | Use |
|
||
| --- | --- |
|
||
| ensure, verify, double-check | make sure, check |
|
||
| utilize | use |
|
||
| perform, carry out | do |
|
||
| prior to | before |
|
||
| commence, initiate | start |
|
||
| terminate, halt | stop |
|
||
| obtain, acquire, fetch | get |
|
||
| allow, enable, permit | let |
|
||
| require, need | is necessary, must |
|
||
| inspect, review | examine |
|
||
| indicate | show |
|
||
| modify, tweak | change |
|
||
| eliminate, drop, strip | remove |
|
||
| additional | more |
|
||
| numerous | many |
|
||
| attempt | try |
|
||
| determine, figure out | find |
|
||
| fix (a fault) | correct, repair |
|
||
| since, as (meaning "because") | because |
|
||
| rather than | instead of |
|
||
| about (a quantity) | approximately |
|
||
| regarding, concerning | about |
|
||
| in order to | to |
|
||
| via (except the relay chain) | through |
|
||
| hand back | return |
|
||
| in view | visible |
|
||
| "e.g.", "i.e.", "etc." | for example, that is, and other ... |
|
||
| simply, just, actually, basically, really | (omit) |
|
||
|
||
## Checks
|
||
|
||
`tests/test_writing_style.py` searches the docstrings, the comments, and the documents for
|
||
the marks that STE does not use: em dashes, semicolons, contractions, and Latin
|
||
abbreviations. It does not search text in code font, text in double quotation marks, code
|
||
blocks, or URLs.
|
||
|
||
A document can contain legal text that must stay exactly as it is (a licence notice, a
|
||
required attribution). Put `<!-- ste: off -->` before such text and `<!-- ste: on -->`
|
||
after it. The test does not search the text between the two markers. Use the markers only
|
||
for legal text.
|
||
|
||
## The source
|
||
|
||
ASD-STE100 is a specification of the AeroSpace and Defence Industries Association of
|
||
Europe (ASD). This page uses Issue 9. The specification itself is available from
|
||
[asd-ste100.org](https://www.asd-ste100.org).
|