docs: 5-loop critical review & polish of this session's work#322
Merged
Conversation
…olon/comma/parentheses) Coding guide (protocol_style_guide): "No em dashes — use a colon for label-like breaks and a comma or parentheses." Fixes the em dashes introduced this session: - getting_started: Decision-Map green box (2), plus the pre-existing "two APIs" bullet label-breaks for page consistency - introduction: quick-reference list lead-in - usage_principles: Data Flow Map lead-in + caption Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…sion-Map alt Loop 2 of the review pass: alt text should avoid em dashes (house style) and a clickable image's alt should signal that it opens something. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Loop 3: the Data Flow lead-in re-described the flow the caption already covers, and the notebook lead-in re-listed notebooks the bullets already show. Both shortened to a single lead sentence (the intro-before-block rule still holds). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Loop 4: integrity check passed (all refs/links resolve). The <summary> visible text is decorative arrows + 'Download'; add an aria-label so screen readers announce a clear name. Kept the Desktop sources + build script in sync. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Loop 5: a full 'make html' shows this session's changes add zero net-new warnings. The one adjacent issue — cheat_sheet.rst emitting 'document isn't included in any toctree' (it is an intentional standalone, like ecosystem.rst) — is fixed by adding :orphan:, matching the pattern I used for ecosystem.rst. Verified: rebuild reports 0 such warnings. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
breimanntools
changed the title
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
1 participant
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.
Five critical review-and-improvement loops over this session's docs (#298–#304, #314), all stacked on this one branch/PR.
Loop 1 — house style (em dashes).
protocol_style_guide.mdbans em dashes. Removed the 6 I introduced (Data Flow caption + lead-in, Getting-Started green box, quick-reference lead-in) plus the adjacent pre-existing "two APIs" bullet label-breaks; colon / comma / parentheses instead.Loop 2 — accessibility & alt text. Em dash out of the ecosystem figure's
:alt:; made the clickable Decision-Map preview's alt signal that it opens the full map.Loop 3 — conciseness. Two lead-ins were redundant: the Data Flow lead-in re-described the flow its caption already covers, and the notebook lead-in re-listed the notebooks the bullets already show. Both cut to one lead sentence (intro-before-block rule preserved).
Loop 4 — link/ref integrity + a11y. Verified every
:ref:,:doc:, and download-menu target resolves (all green). Gave the Download<summary>a properaria-label(its visible text is decorative arrows), kept in sync across the Desktop sources + Data Flow build script.Loop 5 — full
make htmlwarning audit. Build passes; this session's changes add zero net-new warnings (of 439 pre-existing advisories, none touch my files). Fixed the one adjacent issue it surfaced —cheat_sheet.rstlacked:orphan:and emitted a toctree warning — by matching the:orphan:pattern I'd used forecosystem.rst; rebuild confirms the warning is gone.Docs-only.
🤖 Generated with Claude Code