diff --git a/.claude/skills/docs/SKILL.md b/.claude/skills/docs/SKILL.md index d4a494111..32546cf83 100644 --- a/.claude/skills/docs/SKILL.md +++ b/.claude/skills/docs/SKILL.md @@ -177,9 +177,10 @@ that drift most in the current manual: | The physical screen | **the screen** | the display, the panel | | The product | **the PiFinder** | the unit, the device, your device | | Move within a menu | **scroll** | navigate, browse, go to | -| Power on / off | **turn on** / **turn off** | boot, power up, switch on/off | +| Power on / off (reader's action) | **turn on** / **turn off** | power up, switch on/off | +| The machine's startup sequence | **boot** | start up, startup | | A catalog object | **object** | target, DSO | -| The user's telescope | **telescope** | scope, OTA, tube | +| The user's telescope | **telescope** | scope, tube — but keep *polar scope*, *finder scope*, *OTA* | | Go up one menu level | **go back** | return, exit, back out | The full table, the reasoning behind each choice, worked before/after examples, diff --git a/.claude/skills/docs/references/ste-style.md b/.claude/skills/docs/references/ste-style.md index 6e23cd711..9758bc014 100644 --- a/.claude/skills/docs/references/ste-style.md +++ b/.claude/skills/docs/references/ste-style.md @@ -155,8 +155,9 @@ winner was chosen. | A row in a menu | **menu item** | entry, option (see §4) | currently interchangeable | | One of several values | **option** | setting, choice, item (see §4) | option 45 | | Move within a menu | **scroll** | navigate, browse, go to, move to | scroll 20, browse 6, navigate 5 | -| Turn the power on | **turn on** | boot, power up, switch on, start up | turn on 9, boot 14, power on 3 | -| Turn the power off | **turn off** | power down, switch off | turn off 9, switch off 5 | +| Turn the power on (what the reader does) | **turn on** | power up, switch on, start up | turn on 9, power on 3 | +| Turn the power off (what the reader does) | **turn off** | power down, switch off | turn off 9, switch off 5 | +| The machine's own startup sequence | **boot** | start, start up, startup, power-up | boot 14 — see §4 | | The act of shutting down | **shutdown** (noun) | shut-down | shutdown 22 | | Shut the PiFinder down | **shut down** (verb) | shutdown as a verb | shut down 6 | | A catalog object | **object** | target, DSO | object 208, target 22, DSO 11 | @@ -172,17 +173,29 @@ the rest of that page. The manual already does this 67 times and it reads well. ### "telescope", not "scope" -This is the one entry in the table with no evidence winner. The manual uses +This is the one entry in the table that had no evidence winner. The manual used "scope" 72 times and "telescope" 67, near enough a coin flip, and often both in -one paragraph. +one paragraph. **The maintainer settled it: use telescope.** It is unambiguous +for a second-language reader, which is much of the reason this style exists. +"Scope" is shorter, but it is jargon, and it carries other meanings in ordinary +English. -Use **telescope**. It is unambiguous for a second-language reader, which is much -of the reason this style exists. "Scope" is shorter, but it is jargon, and it -carries other meanings in ordinary English. +The manual has been converted, so there is nothing left to sweep. What matters +now is not undoing it, and not over-applying it. -Keep "scope" where it is part of a name or a fixed compound the reader will meet -elsewhere: **OTA** in a parts context, **finder shoe**, **Dobsonian**. Do not -rename existing headings just to apply this. +**Keep "scope" in these four cases.** Each names something that is *not* the +reader's telescope, so renaming it would be a factual error, not a style fix: + +| Keep | Why | +|---|---| +| **polar scope** | The sighting device inside an equatorial mount. "Polar telescope" is not a term anyone uses, and the Polar Alignment section is largely about aligning *without* one. | +| **finder scope** | A separate optical finder. The manual mentions it to contrast it with the PiFinder. | +| **scope type** (SkySafari) | A third-party field label, confirmed against `images/SkySafari/IMG_4796.jpeg`. Quote other products' interfaces exactly. | +| **OTA**, **finder shoe**, **Dobsonian** | Fixed compounds and product names the reader will meet elsewhere. | + +The general rule behind the table: quote any interface exactly as it is labelled, +whether it is PiFinder's or someone else's, and do not rename existing headings +just to apply a term. ### The article on "PiFinder" @@ -219,7 +232,23 @@ hold **SQUARE** and press **+**" makes it worse, not more consistent. **object vs Custom Targets.** *Object* is the general term. *Custom Targets* is a feature name and keeps its capitals and its noun. Do not use "target" as a plain -synonym for object. +synonym for object. A one-off coordinate the reader enters by hand is a **Custom +Target**. An entry that arrives from an observing list is an **object**. + +**turn on vs boot.** These are not synonyms, and collapsing them causes real +damage. **Turn on** is what the reader does to the power button or switch. +**Boot** is the machine's own startup sequence, which continues long after the +reader has let go. + +The distinction is load-bearing here. "The PiFinder won't boot" and "The PiFinder +won't turn on" are different faults with different fixes: a bad SD card lets the +unit power on and then fail to boot. Two headings depend on the word, and +headings are frozen cross-reference targets: + +- `sd_card.rst` — "First boot" +- `troubleshooting.rst` — "The screen is blank, or it won't finish booting" + +So write "turn the PiFinder on", and "the first boot takes longer than usual". **go back vs exit.** **LEFT** goes back one menu level, so write "press **LEFT** to go back." Leaving a mode or tool entirely is "exit", as in "press **SQUARE**