Repository navigation
docs: write the site for people who do not already know the jargon - #8
Merged
Merged
Conversation
Every skill card described the mechanism rather than the mess, in words that only land if you already know the field. Tracking parameters, trailing slashes, byte-identical duplicates, orphans, stubs, tag sprawl, wikilinks, Obsidian vaults. Same failure as naming Vivaldi and expecting recognition, three more times. Cards now describe what the reader recognises in their own machine: the same page saved four times under slightly different links, two versions of the same list, the huge thing you forgot was in there. The coverage table was labelled by storage format, which told a reader nothing. It is labelled by browser family now, in sentences rather than monospace, and the column was widened so they stop wrapping. The sync script keys off that label, so its pattern moved with it and the derived browser list still updates. Contributor steps lost the API and TypeScript framing. Someone writing a text file about tidying their notes app does not need to be told which language they are not writing.
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.
Follows the Vivaldi fix. That was one instance of a pattern; this is the rest of it.
The problem
Every skill card described the mechanism in words that only land if you already know the field:
Now
They describe what the reader recognises in their own machine:
Coverage table
Rows were labelled by storage format —
Chromium JSON,Safari plist,places.sqlite— which tells a normal reader nothing. They are labelled by family now: "Chrome and everything built on it", "Firefox and browsers built on it".Two knock-on fixes that would have broken silently:
sync-skills.pykeys off that<dt>to regenerate the browser chips. Its pattern moved with the label, verified by confirming the derived list still rebuilds.Contributor steps
Lost the "no API, no TypeScript" framing. Someone writing a text file about tidying their notes app does not need to be told which language they are not writing.
109 tests green.