Second README pass: cut explanation the reader does not act on - #244
Merged
Conversation
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>
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
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.
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
du -scsoname counting--oracle+ the--no-*flags skip what you don't needDuplications removed — structurally the same problem
get_genome, thenGenomeManagerdoing the same thing).Core conceptsre-defining "Oracle" and "Track" — both already inKey terms.Key termsre-defining "Conversational genomics" — from the paragraph three lines above it.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
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 installsize 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.