Skip to content

docs: rewrite expected-checksums.md to STE rules - #2041

Open
elharo wants to merge 20 commits into
masterfrom
docs/ste-expected-checksums
Open

docs: rewrite expected-checksums.md to STE rules#2041
elharo wants to merge 20 commits into
masterfrom
docs/ste-expected-checksums

Conversation

@elharo

@elharo elharo commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Rewrite expected-checksums.md to ASD-STE100 Simplified Technical English rules. This PR also includes some pretty hefty human rewrites including:

  • Sonatype Nexus 2 is EOL and was removed
  • Removed paragraph based on incorrect assumption that checksums provided trust and not simply integrity validation

Changes

  • Split long sentences into short sentences. No sentence exceeds 25 words.
  • Removed banned modal verbs (may, might, should, would, could). Replaced them with can, must, or rewrote the sentence.
  • Removed present perfect tenses. Used simple present or simple past instead.
  • Removed banned phrases and vague words: utilize, e.g., in order to, basically, naturally, simply, game changer.
  • Removed "-ing" verb forms in prose. Kept gerunds that function as nouns or adjectives.
  • Split comma-spliced sentences and removed semicolons.
  • Standardized vocabulary. One word has one meaning. For example, verify/verification is used consistently for integrity checks.
  • Kept one topic per paragraph. No paragraph exceeds six sentences.
  • The procedure for the summary checksum file uses the imperative mood with one instruction per step.
  • Verified that all code blocks, identifiers, and command line flags are unchanged.

@elharo
elharo marked this pull request as draft August 6, 2026 10:29
@elharo elharo added the documentation Improvements or additions to documentation label Aug 6, 2026
@elharo
elharo marked this pull request as ready for review August 7, 2026 15:27
@elharo
elharo requested a review from gnodet August 7, 2026 15:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant