docs: convert the software page to the house style - #588
Merged
Conversation
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
"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
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/software.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, neither of them style:
raspi-configsteps rendered as sub-items ofsudo apt upgrade, two levelsbelow 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-configsteps nested under them. Confirmed in the built HTML: the itemnow sits at the same list depth as "SSH into the PiFinder". No wording
changed.
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/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