docs skill: split "turn on" from "boot" in the term table - #599
Merged
Conversation
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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
"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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to the manual-wide conversion (#586-#598), fixing the root cause of the one place three agents disagreed.
The problem
The approved-term table had a single row:
Turn the power on | turn on | boot, power up, switch on, start up. That bans "boot" outright. Three agents hit it and made three different calls:software.rstconverted boot -> start (3 places)sd_card.rstandtroubleshooting.rstdeliberately kept "boot"Why sd_card and troubleshooting were right
They are different concepts. Turn on is what the reader does to the power button. Boot is the machine's own startup sequence, which continues after the reader lets go.
The difference is load-bearing in a troubleshooting context: "won't boot" and "won't turn on" are different faults with different fixes, because a bad SD card lets the unit power on and then fail to boot. And two frozen headings already contain the word, so it cannot leave the manual:
sd_card.rst— "First boot"troubleshooting.rst— "The screen is blank, or it won't finish booting"Changes
software.rstis reverted to "boot" in #588.Found by the cross-page review of the 13 conversion PRs, which is the check no single-page pass can perform.
🤖 Generated with Claude Code
https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD