Skip to content

docs: convert the quick start to the house style - #596

Merged
brickbots merged 5 commits into
mainfrom
docs-ste/quick_start
Aug 10, 2026
Merged

docs: convert the quick start to the house style#596
brickbots merged 5 commits into
mainfrom
docs-ste/quick_start

Conversation

@brickbots

@brickbots brickbots commented Aug 8, 2026

Copy link
Copy Markdown
Owner

Full simplified technical English pass over docs/source/quick_start.rst, using the docs skill's seven rules and approved-term table. Part of the manual-wide conversion, one PR per file.

Measured change

  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

What the converting agent reported

EM_DASHES: 56 -> 1  (the survivor is inside a non-rendered rST maintainer
  comment; left byte-identical so it stays out of the diff)
SEMICOLONS: 16 -> 0
TERMS: scope->telescope x17; unit/device->the PiFinder x5; display->screen x2;
  option->menu item where it means a menu row x5 (option kept for values);
  choose/pick->select x6; push (joystick/telescope)->move x4 ("Push-To" feature
  name untouched); "hold X"->"press and hold X" for single-key long presses x9,
  with the "Hold SQUARE and press +" chord kept per the three-gesture rule;
  switch on/power-on/start-ups/boot -> turn on / turn off;
  "GPS sensor"->"GPS receiver"; "EM noise"->"electromagnetic noise";
  "button press"->"key press"; quoted menu names de-quoted to bare Title Case
STRUCTURAL: 44 sentence splits. Roughly 14 restatement dashes became new
  sentences, 11 paired asides became commas, value lists took a colon, 3
  trailing cross-references became their own sentence. ~12 passives made active.
  Numbered steps re-fronted with command verbs. Net word count unchanged
  (4766 -> 4766). No paragraph reordering; every image, heading and step stays.
LEFT_ALONE: all headings, underlines, levels, :ref:/:doc:/image paths and the
  |min_software| / |v3_docs| substitutions, verified by a token diff against
  HEAD: identical. "The lens focus is set when your PiFinder is assembled" kept
  passive - the actor genuinely does not matter. External link text "click
  here" kept: it is link text, not a device interaction.
FACT_CONCERNS:
  1. "As you sweep the focuser slowly through best focus" - the whole procedure
     is about screwing the CAMERA LENS, not the telescope focuser, so "focuser"
     looks wrong. The fact was not changed; the sentence was rewritten to "As
     you sweep slowly through best focus" so the questionable noun is simply
     absent. Worth a maintainer decision.
  2. The four-bullet key list is flagged in-file as duplicated with
     user_guide.rst (The Menu System). This pass restyled the quick_start copy,
     so the two now diverge more than before. They were ALREADY inconsistent
     ("jumps back to" vs "returns to"). user_guide.rst needs the same two lines
     to re-sync. CROSS-PR ITEM.

Content changes (added after review)

Two follow-up commits restoring meaning the conversion lost:

  • The dropped "needs a few stars" clause is back. 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. 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.
  • "As you sweep slowly through best focus" now names what you turn. The
    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/main that every heading (text and underline character), every :ref:, :doc:, image path, substitution, include:: and external URL is unchanged. Headings matter because autosectionlabel turns 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_CONCERNS above 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

brickbots and others added 5 commits August 7, 2026 23:13
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
@brickbots
brickbots marked this pull request as ready for review August 10, 2026 23:46
@brickbots
brickbots merged commit cfca2ce into main Aug 10, 2026
3 of 4 checks passed
@brickbots
brickbots deleted the docs-ste/quick_start branch August 10, 2026 23:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant