docs: convert the quick start to the house style - #596
Merged
Conversation
Full simplified technical English pass over docs/source/quick_start.rst, applying the seven
rules and the approved-term table from the docs skill.
PASS docs/source/quick_start.rst
em-dash 56->1 | semicolon 16->0 | banned 13->0 | words 4766->4766 (-0%)
terms: choose 5->0, pick 3->0, push 3->0, the display 1->0, the unit 1->0
OVERALL: PASS
Style only. No facts, numbers, procedures or step order were changed.
Headings, cross-references, image paths and substitutions are unchanged,
verified mechanically against origin/main. Sphinx builds clean under -n.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
This four-bullet list is marked in-file as duplicated with user_guide.rst. Both pages were converted independently, so bullets 2 and 4 drifted apart. Review picked the reconciled wording; this is the quick_start half. - Bullet 2: "which either sets it or opens another menu" had an unclear referent for "it", so it becomes "sets an option". - The sync comment is normalised to match user_guide's, which also retires this page's last em-dash. quick_start is now at zero. user_guide gets the matching change on its own branch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
Two changes here were stylistic preference rather than rule compliance, and review flagged both. "We'll get your PiFinder running..." had become "This guide gets your PiFinder running...". "We'll" is simple future, which rule 4 explicitly allows, and the quick start is the one page where a friendly first person earns its place. Restored. "We'll select an object..." had become "You select an object, read some information about it, and move your telescope...", a declarative describing what the reader is about to do. This is a procedure, so rule 3 wants the imperative: "Select an object, read about it, then move your telescope until the object is in the eyepiece." That is shorter than either version. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
The original read "...to learn where it is and what it's looking at, so it needs a few stars to get going." The conversion dropped the trailing clause. Restored as its own sentence rather than re-attached with "so", which keeps the source's meaning without rebuilding a 27-word sentence on a page whose mean is 16. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
The original said "as you sweep the focuser slowly through best focus". That was wrong - the whole procedure turns the camera lens, not a focuser - and the conversion resolved it by deleting the noun, leaving "as you sweep slowly through best focus" with nothing to sweep. "Turn the lens" matches the paragraph directly above, which already says "Turn the lens an eighth to a quarter of a turn at a time". 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
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.
Full simplified technical English pass over
docs/source/quick_start.rst, using thedocsskill's seven rules and approved-term table. Part of the manual-wide conversion, one PR per file.Measured change
What the converting agent reported
Content changes (added after review)
Two follow-up commits restoring meaning the conversion lost:
"...to learn where it is and what it's looking at, so it needs a few stars to
get going." The conversion dropped the trailing clause. It is restored as its
own sentence rather than re-attached with "so", which keeps the meaning
without rebuilding a 27-word sentence on a page whose mean is 16.
original said "sweep the focuser", which was wrong -- the whole procedure
turns the camera lens -- and the conversion resolved it by deleting the noun,
leaving nothing to sweep. It now reads "as you turn the lens slowly through
best focus", matching the paragraph directly above.
Safety
Every other change in this PR is style only. No numbers, procedures or step order were changed.
Verified mechanically against
origin/mainthat every heading (text and underline character), every:ref:,:doc:, image path, substitution,include::and external URL is unchanged. Headings matter becauseautosectionlabelturns each one into a cross-reference target that other pages depend on, and a rename would break them silently.Sphinx builds clean under
-n(nitpicky).Any
FACT_CONCERNSabove that are not listed under Content changes were deliberately not fixed. They are reported for a maintainer decision, since changing them would be a content edit rather than a style one.🤖 Generated with Claude Code
https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD