From 2032f106f57d19520faeb018e105a7f41a72997b Mon Sep 17 00:00:00 2001 From: Richard Date: Fri, 7 Aug 2026 23:37:45 -0700 Subject: [PATCH 1/2] docs skill: split "turn on" from "boot" in the term table Running the style pass across all 13 manual pages exposed a fault in the term table. One row banned "boot" as a synonym for "turn on", so three agents made three different calls: software converted boot -> start, while sd_card and troubleshooting kept it and argued, correctly, that boot names the machine's own startup sequence rather than the reader's action. They are different concepts and the difference is load-bearing. "It won't boot" and "it 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 frozen headings depend on the word, so it cannot leave the manual anyway. The table now has a row for each, and section 4 explains why. Also settled "one-off": a hand-entered coordinate is a Custom Target, an entry from an observing list is an object. Found by the cross-page review of PRs #586-#598, which is the check no single-page pass can perform. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD --- .claude/skills/docs/SKILL.md | 3 ++- .claude/skills/docs/references/ste-style.md | 23 ++++++++++++++++++--- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/.claude/skills/docs/SKILL.md b/.claude/skills/docs/SKILL.md index d4a494111..3b81bea15 100644 --- a/.claude/skills/docs/SKILL.md +++ b/.claude/skills/docs/SKILL.md @@ -177,7 +177,8 @@ 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 | | Go up one menu level | **go back** | return, exit, back out | diff --git a/.claude/skills/docs/references/ste-style.md b/.claude/skills/docs/references/ste-style.md index 6e23cd711..208fdeda1 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 | @@ -219,7 +220,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** From f7248c1441769c4c14856e2659cc62ec385385bf Mon Sep 17 00:00:00 2001 From: Richard Date: Sat, 8 Aug 2026 16:29:53 -0700 Subject: [PATCH 2/2] docs skill: record the telescope decision and its exceptions "telescope vs scope" was the one term-table row with no evidence winner (72/67 in the old manual). The maintainer has settled it: telescope. The manual is now converted, so the risk shifts from under-applying the term to over-applying it. Four things keep "scope" because they name something that is not the reader's telescope, and renaming them would be a factual error rather than a style fix: - polar scope - the sighting device inside an equatorial mount, and the Polar Alignment section is largely about aligning without one - finder scope - a separate optical finder, mentioned to contrast it with the PiFinder - SkySafari's "scope type" - a third-party field label - OTA, finder shoe, Dobsonian - fixed compounds and product names Also fixes a contradiction this exposed: SKILL.md's compact table listed OTA in the "not these" column while the reference treats it as legitimate in a parts context. The general rule now stated once: quote any interface exactly as labelled, whether it is PiFinder's or someone else's. Manual-side change is in #600. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD --- .claude/skills/docs/SKILL.md | 2 +- .claude/skills/docs/references/ste-style.md | 28 +++++++++++++++------ 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/.claude/skills/docs/SKILL.md b/.claude/skills/docs/SKILL.md index 3b81bea15..32546cf83 100644 --- a/.claude/skills/docs/SKILL.md +++ b/.claude/skills/docs/SKILL.md @@ -180,7 +180,7 @@ that drift most in the current manual: | 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 208fdeda1..9758bc014 100644 --- a/.claude/skills/docs/references/ste-style.md +++ b/.claude/skills/docs/references/ste-style.md @@ -173,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"