Skip to content

Sort docs by reader intent - #373

Merged
vincebln2 merged 4 commits into
VibiumDev:mainfrom
vincebln2:docs/sort-docs-328
Aug 19, 2026
Merged

Sort docs by reader intent#373
vincebln2 merged 4 commits into
VibiumDev:mainfrom
vincebln2:docs/sort-docs-328

Conversation

@vincebln2

Copy link
Copy Markdown
Collaborator

Fixes #328.

The docs taxonomy already defines tutorials as learning, how-to guides as doing, reference as lookup, and explanation as understanding, but several files still lived in the wrong quadrant or duplicated one guide per language.

What changed

  • Merged the JavaScript and Python downloads docs into one how-to guide, and did the same for accessibility trees
  • Moved window and viewport guidance into how-to, recording format into reference, and maintainer setup/publishing runbooks into contributing
  • Renamed the misspelled classic WebDriver reference while retaining one BiDi explanation and one BiDi protocol reference
  • Updated every inbound link and the executable tutorial test paths
  • Kept using-firefox.md and record-video.md at their existing paths; the Firefox capability table is unchanged

Verified:

  • Relative Markdown link audit passes across the repository, excluding the vendored W3C spec syntax
  • JS and Python tutorial parsers discover all annotated tests at their merged paths
  • git diff --check passes

vincebln2 and others added 4 commits August 19, 2026 12:03
The tutorial extractors skip code fences of other languages without
consuming the pending test marker. In a doc that mixes JavaScript and
Python blocks, the last JavaScript marker stayed pending until the first
python fence anywhere in the file, so the Python sync suite picked up a
phantom test whose body was the doc's standalone server example. That
block calls serve_forever, which hung the suite until CI's 600s kill.
Any fenced block now consumes the pending marker: it binds to the code
block immediately after it or not at all. Same fix in both runners.

Collected tests now match the pre-merge docs exactly (downloads 2+2,
a11y 10+13); the phantom onDownload entry is gone.
@vincebln2
vincebln2 merged commit c63b247 into VibiumDev:main Aug 19, 2026
3 checks passed
@vincebln2
vincebln2 deleted the docs/sort-docs-328 branch August 21, 2026 18:40
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.

Docs: sort tutorials / how-to / reference / explanation cleanly

1 participant