Skip to content

docs: write the site for people who do not already know the jargon - #8

Merged
vamgan merged 1 commit into
mainfrom
docs/plain-language
Aug 25, 2026
Merged

vamgan merged 1 commit into
mainfrom
docs/plain-language

Conversation

@vamgan

@vamgan vamgan commented Aug 25, 2026

Copy link
Copy Markdown
Owner

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:

Dedupes across tracking parameters, www, and trailing slashes.
Finds byte-identical duplicates.
An Obsidian vault or any folder of markdown. Finds orphans, stubs, and tag sprawl, without breaking your [[wikilinks]].

Now

They describe what the reader recognises in their own machine:

The same page saved four times under slightly different links. Bookmarks that no longer go anywhere. Folders holding one thing.
The same file saved twice, things you have not opened in months, and the huge items you forgot were there.
Notes you started and never finished. Two versions of the same list. Half a dozen tags that all mean the same thing.

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:

  1. The labels were styled monospace, which suited format names and looks wrong on sentences, and wrapped in a 220px column. Now sans, 280px.
  2. sync-skills.py keys 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.

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.
@vamgan
vamgan merged commit 12119b2 into main Aug 25, 2026
7 checks passed
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