Skip to content

docs: convert the shared camera includes to the house style - #594

Merged
brickbots merged 3 commits into
mainfrom
docs-ste/includes
Aug 10, 2026
Merged

docs: convert the shared camera includes to the house style#594
brickbots merged 3 commits into
mainfrom
docs-ste/includes

Conversation

@brickbots

Copy link
Copy Markdown
Owner

Full simplified technical English pass over docs/source/includes/camera_prep.rst and docs/source/includes/camera_cable_connect.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/includes/camera_prep.rst
     em-dash 1->0 | semicolon 2->0 | banned 0->0 | words 293->290 (-1%)
  PASS  docs/source/includes/camera_cable_connect.rst
     em-dash 1->0 | semicolon 1->0 | banned 0->0 | words 157->152 (-3%)
OVERALL: PASS

What the converting agent reported

EM_DASHES: 2 -> 0  (both were in non-rendered maintainer comments, not prose)
SEMICOLONS: 3 -> 0
TERMS: board->PCB (PCB already used 4x in the same file for the same part);
  "the dark-grey piece"->"the dark-grey clip" (file used piece/clip for one
  part; now clip x3); "insert the cable"->"slide the cable in" (matching the
  file's own existing phrasing); "Situate"->"Place"
STRUCTURAL: no headings added or changed, no steps reordered, every image path
  byte-identical. Sentence-level splits only. 293->290 and 157->152 words.
LEFT_ALONE: every caution kept and, where modality moved, only strengthened
  ("should sit neatly" -> "must sit neatly" as a fit criterion). Kept "adapter"
  rather than resolving it: the two parent pages disagree with each other on
  this word, and picking one would make the shared text fit the other parent
  worse. Kept "Flip the camera assembly over" because build_guide.rst says
  "Flip the unit over" immediately after the include. No sentence added that
  assumes either a fresh build or an upgrade.
FACT_CONCERNS: "They match the other four, in case they get mixed up" is
  elliptical. Rendered as the plain reading ("so it does not matter if they get
  mixed up"); if the intent was the opposite (keep them separate), this needs a
  maintainer fix.

Safety

Style only. No facts, 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 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 3 commits August 7, 2026 23:09
Full simplified technical English pass over docs/source/includes/camera_prep.rst docs/source/includes/camera_cable_connect.rst, applying the seven
rules and the approved-term table from the docs skill.

  PASS  docs/source/includes/camera_prep.rst
     em-dash 1->0 | semicolon 2->0 | banned 0->0 | words 293->290 (-1%)
  PASS  docs/source/includes/camera_cable_connect.rst
     em-dash 1->0 | semicolon 1->0 | banned 0->0 | words 157->152 (-3%)
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 was the only PR in the conversion that changed modality, and modality is
meaning rather than style. Review flagged four places; all are restored.

- "It should sit neatly in the square recess" and "It should stay open as you
  insert the cable" had both become "must". Each is arguable as a fit
  criterion, but the source hedged and a style pass should not decide that.
- "It helps to remove the black plastic portion..." had become an imperative,
  which reads as a mandatory pliers-on-the-camera-PCB step. It is optional
  advice, so it is now "you can pull the black plastic part off".
- "as close to the board as you reasonably can" had lost "reasonably".

The rest of the conversion on these two files stands: the terminology
unification (board -> PCB, piece -> clip) and the sentence splits are style,
and every caution still reads with at least its original force.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HqTCarGCgTRWBQ1ysG8XFD
"Flip the camera assembly over. Thread the lens in slowly and
carefully. Use gentle force." is four sentences in a row for one
careful movement, and a two-word imperative reads as a separate step.
The style asks for shorter sentences, not staccato in a delicate
procedure.

No fact or instruction changed; the gentle force is now a condition of
the same movement rather than a step of its own.

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