docs(en): polish English prose and fix stale references#418
Merged
Conversation
A native-quality audit of the English pages (OWASP-reviewer lens) found the prose generally strong, with a short list of high-impact issues. Fix them: - Real defects: the by-input firmware links were tagged "(Korean)" but point at the English guide; architecture.md pinned ScanCode 32.3.0 and Trivy v0.70.0 while the Dockerfile ARGs say 32.5.0 / v0.72.0. - Literal or off collocations: "do not easily abort", "decisively better", "gathered as", "hand outputs back and forth", "it is a later addition", "identifies components two ways". - Readability: split the two heaviest run-on passages (ui.md advanced options, reports-explained deps.dev bullet), new paragraph for the public-repo caveat in identify-vendored.md, drop a doubled "immediately", fix a heterogeneous "such as" list. - Consistency: "quality criteria" throughout supplier-sbom.md, "Quick start" heading spelling, spelled-out first-/third-party in prose, link text aligned with the target page's title. Korean mirrors are unaffected (EN-only prose changes; the ko firmware links were verified correct as-is).
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.
Why
A native-quality audit of the 24 English site pages plus the README (through an OWASP-reviewer lens) rated the docs strong overall, with a short list of high-impact findings: two real defects and a set of literal collocations, run-ons, and consistency drifts.
What
Real defects
by-input.md: two firmware-guide links were tagged "(Korean)" but point at the English guide — misleading to a reviewer. Tags removed (the ko mirror was verified correct as-is).architecture.md: tool table pinned ScanCode32.3.0and Trivyv0.70.0; the Dockerfile ARGs are32.5.0/v0.72.0. Pins refreshed.Prose polish (meaning preserved)
Verification
tests/check-docs-drift.sh,scripts/check-doc-coverage.sh— passmkdocs build --strict— exit 0 (renamed heading has zero inbound anchor links, verified repo-wide)