Skip to content

docs: convert the build guide to the house style - #598

Merged
brickbots merged 6 commits into
mainfrom
docs-ste/build_guide
Aug 10, 2026
Merged

docs: convert the build guide to the house style#598
brickbots merged 6 commits into
mainfrom
docs-ste/build_guide

Conversation

@brickbots

@brickbots brickbots commented Aug 8, 2026

Copy link
Copy Markdown
Owner

Full simplified technical English pass over docs/source/build_guide.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/build_guide.rst
     em-dash 0->0 | semicolon 13->0 | banned 52->44 | words 5211->5213 (+0%)
     terms: the display 3->0, the unit 3->0, navigate 2->0
OVERALL: PASS

What the converting agent reported

EM_DASHES: 0 -> 0
SEMICOLONS: 13 -> 0  (all were rule-1 clause welds)
TERMS: the big win here is hardware-name unification.
  UI Hat / UI Board / UI Module / "the hat" / "PiFinder hat" / "custom 'Hat'"
    -> UI Hat everywhere (matching the locked heading "PiFinder UI Hat")
  Pi Mount / PiMount / PI Mount / RPI Mount / RPI Holder / "the mount plate"
    -> Pi Mount (matching the locked heading "Pi Mount")
  GPS unit->GPS module; display->the screen; scope->telescope;
  "dobsonians"->"Dobsonians"; unit->the PiFinder or build; keyboard->keypad;
  "inertial motion sensor"->IMU; navigate/go to->scroll/select;
  the glyph paths "Tools > Status" and "Objects > Name Search" replaced with
  prose chains; "power it up"->"turn the PiFinder on"; zip-ties->zip ties
STRUCTURAL: ~40 two-clause sentences split; ~25 procedural sentences reordered
  to lead with the command verb ("Switches go next"->"Fit the switches next").
  Passives made active ("is soldered from the top"->"Solder it from the top").
  Rule 6 noun stacks unpacked ("bottom plate mounting footprint"->"the mounting
  footprint on the bottom plate"). One inline "NOTE:" paragraph converted to a
  real .. note:: admonition.
LEFT_ALONE: every heading, underline and level verified byte-identical; all
  image/:target:/:alt: lines; both .. include:: lines; all tables. The heading
  "Display" kept although the body now says "screen", because headings are
  :ref: targets. First-person author voice in Printing/Inserts ("I use 3
  perimeter layers") and the closing "Congratulations, you have a PiFinder!"
  kept as genuinely delightful moments. No rev4 content or scoping added.
FACT_CONCERNS:
  1. Camera version drift: the Camera Prep lead-in says "The new v3 camera",
     but the page's top note scopes the whole guide to v2.5 hardware and a
     later note says "the v2.5 camera". Same part, two names.
  2. "Rigel Quickfinder" (heading + 2 mentions) vs "Rigel Quikfinder" (2
     mentions). The real product is "Quikfinder"; the heading is locked, so
     both spellings survive.
  3. common_1b.jpeg uses ":target: _images/common_1b.jpeg" while every other
     image targets its source path - looks like a stale build-output path.
  4. "Snip the zip ties off, then move on." follows the step that secures the
     battery WITH zip ties. It most likely means trim the tails, but the verb
     is ambiguous, so it was preserved.

Content changes (added after review)

Four follow-up commits. One of them renames a heading, which this conversion
otherwise never did -- see the note below.

  • The Rigel Quikfinder is spelled correctly. Rigel's product is the
    Quikfinder. The guide used "Quickfinder" in the section heading, its lead-in
    sentence and the base-plate paragraph, while that same paragraph spelled it
    "Quikfinder" twice. The two STL names were wrong as filenames, not just as
    prose: the files in case/adapters/quikfinder/ are
    PiToQuikfinder v2 - Part 1.stl and ... Part 2.stl, so a reader searching
    the repo for the documented name finds nothing. The quickfinder_base_*.jpeg
    image paths keep their spelling -- those are real filenames on disk.
  • Three links to the adapter parts were 404s. All three "git repo
    quikfinder" links pointed at case/adapter/quikfinder. That directory has
    never existed; the parts live in case/adapters/quikfinder (plural) on both
    main and release. It is the only broken case/ link in the manual.
  • The photo caveat names the v3 camera. Line 512 calls the part "the new v3
    camera"; the note called the same part "the v2.5 camera". The v2.5 build uses
    the v3 camera, as v25_upgrade.rst says.
  • "Snip the zip ties off" says which part to snip. It could mean trim the
    tails or remove the ties. The step above installs those ties to hold the
    battery, so removing them would undo it. Now "Snip off the loose ends of the
    zip ties".

About the heading rename

Rigel Quickfinder Assembly -> Rigel Quikfinder Assembly. Checked before
making it: no :ref: or :doc: in the manual targets
build_guide:rigel quickfinder assembly -- not on main, and not on any of the
14 docs-ste branches. The only occurrence anywhere is the heading definition
itself. A nitpicky Sphinx build of this branch, and a full integration build of
all 14 branches merged together, are both clean.

verify_ste.py therefore reports two expected failures for this PR:
HEADINGS CHANGED for the rename, and url LOST / url added for the three
corrected links. Both are deliberate.

  • 43 of the 44 click-to-enlarge links were dead. Every image on this page
    links to itself so a reader can click for a full-size view. Sphinx copies
    image sources into _images/ and rewrites the <img src> to match, but it
    emits a :target: value verbatim as an href -- so targets written as
    source-tree paths (images/build_guide/x.jpeg,
    ../../images/build_guide/x.jpeg) resolve against the built page and 404.
    Audited the built HTML: 1 of 44 targets resolved before, 44 of 44 after.
    The one that worked was :target: _images/common_1b.jpeg, which the review
    flagged as the odd one out -- it was in fact the only correct one, and every
    other page in the manual already uses that form. Checked for basename
    collisions first, since Sphinx renames on collision and _images/<basename>
    would then be wrong; there are none on this page.

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

Full simplified technical English pass over docs/source/build_guide.rst, applying the seven
rules and the approved-term table from the docs skill.

  FAIL  docs/source/build_guide.rst
     em-dash 0->0 | semicolon 13->0 | banned 52->44 | words 5211->5213 (+0%)
     terms: the display 3->0, the unit 3->0, navigate 2->0
     !! ref LOST: ['"the menu"<user_guide:the menu system>', '3d printing<build_guide:printed parts>', 'GPS<build_guide:gps>', 'Testing the Backlight<build_guide:testing the backlight>']
     !! ref added (check): ['3d printing <build_guide:printed parts>', 'GPS <build_guide:gps>', 'Status screen <user_guide:status screen>', 'Testing the Backlight <build_guide:testing the backlight>']
     !! doc LOST: ['Bill of Materials<BOM>', 'Software Setup<software>', 'software setup<software>']
     !! doc added (check): ['Bill of Materials <BOM>', 'Software Setup <software>', 'software setup <software>']
OVERALL: FAIL - do not open PRs for failing files

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
brickbots and others added 5 commits August 8, 2026 17:58
Rigel's product is the Quikfinder. The guide used "Quickfinder" in the
section heading, its lead-in sentence, and the base-plate paragraph,
while the same paragraph spelled it "Quikfinder" twice.

The two STL names were wrong as filenames, not just as prose: the files
in case/adapters/quikfinder/ are "PiToQuikfinder v2 - Part 1.stl" and
"... Part 2.stl". A reader searching the repo for the documented name
finds nothing.

This renames a heading, which the conversion otherwise never did.
Checked first: no :ref: or :doc: in the manual targets
"build_guide:rigel quickfinder assembly" — on main or on any of the 14
docs-ste branches — and the nitpicky Sphinx build is clean. verify_ste
reports HEADINGS CHANGED for this commit by design.

The quickfinder_base_*.jpeg image paths keep their spelling; those are
real filenames on disk.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
All three "git repo quikfinder" links pointed at
case/adapter/quikfinder. That directory has never existed: the parts
live in case/adapters/quikfinder (plural) on both main and release.
Anyone following the link to download the STLs got a GitHub 404.

Found while correcting the Quikfinder spelling on the same lines. It is
the only broken case/ link in the manual; the other one
(case/v2) resolves.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
Line 512 calls the part "the new v3 camera"; this note called the same
part "the v2.5 camera". The v2.5 build uses the v3 camera - v25_upgrade
describes the kit as bringing "your PiFinder's camera up to v3
capabilities" - so v3 is the right name in both places.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
"Snip the zip ties off" could mean trim the tails or remove the ties.
The step above installs those ties to hold the battery and says to
tighten them "just enough to keep the battery from moving", so removing
them would undo the step just performed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
Every image on this page linked to itself so a reader could click for a
full-size view. 43 of the 44 links were dead.

Sphinx copies image sources into _images/ and rewrites the <img src> to
match, but it emits a :target: value verbatim as an href. Targets
written as source-tree paths - "images/build_guide/x.jpeg",
"../../images/build_guide/x.jpeg" - therefore resolve against the built
page and 404.

Audited the built HTML: 1 of 44 targets resolved before this commit, 44
of 44 after. The one that worked was ":target: _images/common_1b.jpeg",
which the review had flagged as the odd one out; it was in fact the only
correct one, and every other page in the manual already uses that form.

Checked for basename collisions first, since Sphinx renames on collision
and _images/<basename> would then be wrong. There are none on this page.

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:42
@brickbots
brickbots merged commit 0369498 into main Aug 10, 2026
4 checks passed
brickbots added a commit that referenced this pull request Aug 10, 2026
* 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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD

* 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) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
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