Skip to content

Second README pass: cut explanation the reader does not act on - #244

Merged
lucapinello merged 1 commit into
mainfrom
docs/2026-08-18-readme-less-lecturing
Aug 18, 2026
Merged

Second README pass: cut explanation the reader does not act on#244
lucapinello merged 1 commit into
mainfrom
docs/2026-08-18-readme-less-lecturing

Conversation

@lucapinello

Copy link
Copy Markdown
Contributor

Prompted by a fair callout: "A volume sold as 100 GB is 93.1 GiB, so it fits with ~2 GiB spare" is a units
lesson, not something anyone provisioning a disk uses. The first pass moved caveats out of the reading path;
this one removes over-explanation in it.

One rule throughout: keep what changes what a user does, cut what only explains how we know it or why we
chose it.

Lectures removed

cut why
decimal-vs-binary lesson on the free-disk bullet you need the number, not the arithmetic
~15 lines on why conda envs are large — pip hardlinking, du -sc soname counting reduced to the two facts you act on: macOS/CPU installs are smaller, and --oracle + the --no-* flags skip what you don't need
a note explaining that two of our own tables size the same files in different units fixing our inconsistency is not the reader's job
what an earlier audit measured on other hardware, in the equivalence claim mine, from yesterday; current numbers are what matter
the history of the downloader's previous "only fetch when missing" rule the rule is useful, its predecessor is not
my postmortem in Caveats about why our test missed the splice bug you need the state and the action, not our test-design retrospective

Duplications removed — structurally the same problem

  • A BedGraph "example" that was three comments and a pointer to the real recipe.
  • Two ways to load the identical genome (get_genome, then GenomeManager doing the same thing).
  • Core concepts re-defining "Oracle" and "Track" — both already in Key terms.
  • Key terms re-defining "Conversational genomics" — from the paragraph three lines above it.
  • The credentials/conda-env rule stated in two separate places.

Plus two structural fixes: an aside was splitting the two-item token list, and "the wrong place for 85 GB"
was a third stale copy of a total that had moved to 87.

Cumulative since v0.7.5

at v0.7.5 now
aside text 12,229 chars 6,409 (−48%)
longest aside 1,692 704
prose lines > 420 chars 17 8
README 99,211 chars 91,959

One guard deleted rather than satisfied

test_the_tldr_install_size_agrees_with_the_disk_table — I wrote it yesterday to keep the TLDR's install
size in sync with the disk table. The TLDR no longer states an install size, so there is nothing to keep in
sync. Removing the duplicate removed the reason for the guard; re-adding the number to keep a test green
would have been backwards.

Fast suite 2,144 passed / 35 skipped. The skip count rose by one because the changelog-vs-tag guard
correctly skips on an untagged branch HEAD — not lost coverage, checked rather than assumed.

The first pass moved caveats out of the reading path. This one removes over-explanation *in* it, prompted by
a fair callout: "A volume sold as 100 GB is 93.1 GiB, so it fits with ~2 GiB spare" is a units lesson, not
information anyone provisioning a disk uses.

One rule applied throughout: keep what changes what a user does, cut what only explains how we know it or
why we chose it. Removed on that basis:

* the decimal-vs-binary lesson on the free-disk bullet, and the second copy of the install total with it
* ~15 lines on why conda envs are large -- pip's hardlinking behaviour, how `du -sc` counts sonames -- down
  to the two facts a reader acts on (macOS/CPU installs are smaller; `--oracle` and the `--no-*` flags skip
  what you don't need)
* a note explaining that two of our own tables size the same files in different units
* what an earlier audit measured on other hardware, in the backend-equivalence claim (mine, from yesterday)
* the history of the background downloader's previous "only fetch when missing" rule
* my own postmortem in Caveats about why our test missed the splice bug -- a user needs the state and the
  action, not our test-design retrospective

And five duplications, which are the same problem structurally:

* a BedGraph "example" that was three comments and a pointer to the real recipe
* two ways to load the identical genome (get_genome, then GenomeManager doing the same thing)
* `Core concepts` re-defining "Oracle" and "Track", both already in `Key terms`
* `Key terms` re-defining "Conversational genomics" from the paragraph three lines above
* the credentials/conda-env rule stated in two separate places

Plus two structural fixes: an aside was splitting the two-item token list, and "the wrong place for 85 GB"
was a third stale copy of a total that moved to 87.

Cumulative since v0.7.5: aside text 12,229 -> 6,409 chars (-48%), longest aside 1,692 -> 704, prose lines
over 420 chars 17 -> 8, README 99,211 -> 91,959 chars.

`test_the_tldr_install_size_agrees_with_the_disk_table` is deleted rather than satisfied: I wrote it to keep
the TLDR's install size in sync with the disk table, and the TLDR no longer states an install size, so there
is nothing to keep in sync. Removing the duplicate removed the reason for the guard.

Fast suite 2,144 passed / 35 skipped. The skip count rose by one because `test_the_changelog_has_no_unreleased_entries_when_tagged` correctly skips on an untagged branch HEAD -- not lost coverage.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@lucapinello
lucapinello merged commit 721393f into main Aug 18, 2026
2 checks passed
@lucapinello
lucapinello deleted the docs/2026-08-18-readme-less-lecturing branch August 18, 2026 12:39
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