Writing style
The pages on this site follow ASD-STE100 Simplified Technical English where it helps. The aim is text that is clear to every reader, including readers whose first language is not English. The rules are a strong preference, not a strict requirement.
- One topic per sentence, one instruction per step.
- Short sentences. Procedures: 20 words or fewer. Descriptions: 25 words or fewer.
- Short paragraphs. One topic, six sentences or fewer.
- Active voice. “The ATOM sends the packet”, not “The packet is sent”.
- Imperative in procedures. “Connect the cable.” Put a condition before the instruction: “If the LED is red, press the button.”
- One word for one thing. Use the terms below. Do not change the term for variety.
- Simple verb tenses: present, simple past, future. No “-ing” forms as verbs.
- Use articles (“the”, “a”) where they are normal in English.
- Numbers with units, and the measured value, not “fast” or “slow”.
- Warnings before the step they apply to. Use the
cautionanddangerboxes.
Technical names (register names, function names, file names) are allowed as they are.
| Use | Do not use |
|---|---|
| ATOM | M5, controller, end board |
| servo bus | serial bus, servo line |
| laptop | host, PC, computer |
| FT232R | FTDI, USB adapter (except to explain) |
| base | transponder, bottom board |
| plan | trajectory file, path |
| recording | log, capture (for player output) |
| goal position, goal speed | target, setpoint (for servo registers) |
| hold the pose | lock, freeze |
| lag compensation | time shift, feedforward (for this method) |
Keep the site true
Section titled “Keep the site true”- This site is the source of truth. When code changes, change the page in the same commit.
- Write what is measured, with the date and the numbers. Mark what is not verified.
- Do not delete a wrong statement silently. Correct it, and say what changed if readers can have seen it.