Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .claude/skills/docs/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
51 changes: 40 additions & 11 deletions .claude/skills/docs/references/ste-style.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand All @@ -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"

Expand Down Expand Up @@ -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**
Expand Down
Loading