Skip to content

docs: convert the software page to the house style - #588

Merged
brickbots merged 4 commits into
mainfrom
docs-ste/software
Aug 10, 2026
Merged

docs: convert the software page to the house style#588
brickbots merged 4 commits into
mainfrom
docs-ste/software

Conversation

@brickbots

@brickbots brickbots commented Aug 8, 2026

Copy link
Copy Markdown
Owner

Full simplified technical English pass over docs/source/software.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/software.rst
     em-dash 0->0 | semicolon 1->0 | banned 6->1 | words 936->914 (-2%)
     terms: choose 5->1, the unit 1->0
OVERALL: PASS

What the converting agent reported

EM_DASHES: 0 -> 0
SEMICOLONS: 1 -> 0
TERMS: "deep sky catalog images" -> "deep-sky catalog images" (the manual's one
  real four-noun stack, rule 6); choose->select x3 (literal imager buttons
  'Choose OS'/'Select Storage' left verbatim); "the unit"->"your PiFinder";
  "power it up"->"turn it on" x2; boot->start x3; reboot->restart;
  wifi/Wifi/WIFI -> WiFi x7 (dominant form elsewhere in the manual);
  pre-built->prebuilt; "sd card"->"SD card"; burn->write (matches the
  imager's own Write button)
STRUCTURAL: no reorders. 5 run-ons split. Passives made active ("SSH is enabled
  on this image" -> "This image enables SSH"). Flashing steps made imperative.
  Auxiliary chains cut ("will probably take" -> "takes"). 936 -> 914 words.
LEFT_ALONE: all 5 headings and underlines (:ref: targets used by sd_card.rst,
  dev_guide.rst and user_guide.rst); every command, URL, code block and the
  blockquote around the wget line; step order in both procedures; contractions,
  which are the manual's register and not forbidden by STE.
FACT_CONCERNS:
  1. Likely mis-indentation, left as found: the five SPI/I2C bullets are nested
     under the "sudo apt upgrade" bullet, so they render as sub-steps of the
     upgrade rather than a separate setup step. Fixing it changes structure.
  2. Three images escape docs/source/ into the repo-root images/ tree, unlike
     the four images/software/... paths on the same page. All exist, build is
     clean, but it breaks the per-page images/<page>/ convention. Pre-rev4 shots.
  3. "Build From Scratch" still specifies 64-bit Pi OS Legacy (Bullseye). If the
     supported base OS has moved on, this section is stale.

Content changes (added after review)

Two follow-up commits, neither of them style:

  • The SPI/I2C steps were mis-nested. "Enable SPI / I2C" and its four
    raspi-config steps rendered as sub-items of sudo apt upgrade, two levels
    below where they belong, which made enabling the buses look like part of
    updating packages. They are now a sibling of "Update all packages", with the
    raspi-config steps nested under them. Confirmed in the built HTML: the item
    now sits at the same list depth as "SSH into the PiFinder". No wording
    changed.
  • The last stray "reboot" is now "boot". The page normalised
    reboot -> restart everywhere else, leaving one "start on reboot". "restart" is
    the wrong replacement: the service starts on every boot, not only after a
    restart. Under the settled turn on vs boot rule (docs skill: split "turn on" from "boot" in the term table #599), "boot" is the
    approved word for the machine's own startup sequence.

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 2 commits August 7, 2026 23:09
Full simplified technical English pass over docs/source/software.rst, applying the seven
rules and the approved-term table from the docs skill.

  PASS  docs/source/software.rst
     em-dash 0->0 | semicolon 1->0 | banned 6->1 | words 936->914 (-2%)
     terms: choose 5->1, 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
The style pass converted boot -> start here, but sd_card and troubleshooting
deliberately kept "boot", and cross-page review found they are right.

Two frozen headings contain the word - sd_card's "First boot" and
troubleshooting's "The screen is blank, or it won't finish booting" - so it
cannot leave the manual. This page had ended up contradicting a page it links
to with near-identical sentences: sd_card says "The first boot from a freshly
imaged card takes longer than usual", while this said "The first start...".

The approved term "turn on" still covers the user action. "boot" covers only
the machine's own startup sequence. The two are different concepts, and the
term table needs a row saying so - noted for a skill follow-up.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
brickbots and others added 2 commits August 8, 2026 17:55
"Enable SPI / I2C" and its four raspi-config steps rendered as
sub-items of "sudo apt upgrade", two levels below where they belong,
which made enabling the buses look like part of updating packages.

Promote it to a sibling of "Update all packages" and nest the
raspi-config steps under it. Verified in the built HTML: the item now
sits at the same list depth as "SSH into the PiFinder".

Wording unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
The page normalised reboot -> restart everywhere else, leaving one
"start on reboot".

"restart" is the wrong replacement here: the service starts on every
boot, not only after a restart. Under the settled turn on vs boot rule,
"boot" is the approved word for the machine's own startup sequence, so
"start on boot" is both accurate and in style.

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:41
@brickbots
brickbots merged commit b9f9ccc into main Aug 10, 2026
4 checks passed
@brickbots
brickbots deleted the docs-ste/software branch August 10, 2026 23:41
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