WebAssembly / WebAssembly/spec

Can we simplify doc navigation?

Open
#1,558 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
WebAssembly
Stars
3.5k
Forks
539
Avg merge
2d 1h
Merged PRs (30d)
13

Description

I see some problems with the instruction summary table.

  • If you Ctrl+F and look for, say, "call_indirect", there is no text highlighting. The screen may scroll appropriately, but you can't easily find what you're looking for. Probably just a simple CSS or font fix.

  • If you then click on "call_indirect", it brings you to a page about the more generic concept of control transfers. That's like clicking "zebra" and being redirected to an article about zoos.

  • If you actually type "call_indirect" into the search dialog into the left pane, then click "Go", you'll end up with nothing at all (or sometimes a search-engine-style dump of vaguely relevant pages). (This might be more acceptable if the previous point were addressed.)

Navigating the docs, and instruction definitions in particular, should be trivial. Even an unweildy 1000-page PDF would be superior to the current state of affairs.

That's all I have to say about this. The team knows what best to do about it.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the instruction summary at appendix/index-instructions.html and inspect the left-pane search behavior and links for entries such as "call_indirect." Compare browser find highlighting, instruction links, and search results against the issue's examples; done means navigation makes instruction lookup direct and usable.

Written by the indexing model from the issue text.

Assessment

Tech stack
wasm
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.