Skip to Main Content
Lightning Talk Beginner Apache License, Version 2.0 First Talk

Docs You Can Run: Live, Editable Examples in wgblas

Proposal status is Review Pending
Session Description

Most project docs show you a code snippet and trust you to copy it into your own environment to see if it actually works. wgblas’s docs don’t ask for that trust: every code example on the reference pages is a live, editable CodeMirror block with a Run button, and hitting Run executes it against the real WebGPU build, right there on the page. No install, no console, nothing to set up.

This talk is a short walkthrough of how that’s built and why it matters for a library like a GPU BLAS, where “does this actually work on your hardware” is a real question a static snippet can’t answer. I’ll show the docs live: open a routine’s page, edit the example inline, change an input, hit run, and watch the output change in the browser. I’ll also cover how the examples stay in sync with the source (they’re pulled from the project’s examples/ folder at build time rather than hand-copied into the docs, so the two can’t drift apart) and why every example uses small, hand-checkable numbers instead of random arrays, so a reader can verify correctness themselves rather than trust the demo.

The goal is to make the case that for anything hardware- or platform-dependent, runnable docs aren’t a nice-to-have, they’re how you actually prove the thing works.

Key Takeaways

  • A pattern for making documentation runnable instead of just readable, using nothing more than an in-browser code editor and the library’s own build.

  • Why pulling examples from the project’s source at build time (instead of hand-copying snippets into docs) keeps documentation from quietly going stale.

  • Why small, hand-verifiable example inputs build more trust than impressive-looking random data.

  • Where this approach helps most: anything where “it works” depends on the reader’s own hardware or environment.

References

Session Categories

Tutorial about using a FOSS project
Talk License: Apache License, Version 2.0
Speakers are hidden and anonymized for this event.