Skip to content
Field Guides

Requesting a guide

If a topic isn’t here yet, request it. A good request takes two minutes to write and saves hours of back-and-forth, because the missing pieces are almost always the same five.

What to include

Section titled “What to include”

Give the requester (a person or an agent — the pipeline is the same) the following, in rough priority order:

  1. Topic — one sentence. “How to use Triton” beats “GPU stuff”.
  2. Audience — who will read it and what they already know. “ML engineer, strong Python and PyTorch, has never written a GPU kernel” tells the author exactly where to start and what to skip.
  3. Depth — the level of working knowledge wanted. “Can write and debug their own kernels afterwards” is a different guide from “just wants a working example to copy”.
  4. Target environment — OS, language versions, hardware. This becomes targetEnv and decides what can be marked verified versus untested. No GPU on the author’s side? Say so — the guide will be honest about it.
  5. Must cover / out of scope — the checklist and the fence. “Must cover: memory coalescing, autotuning, a fused softmax. Out of scope: multi-GPU” produces a focused guide; an empty fence produces a rambling one.

Nice to have: how many pages you’d expect (6–8 is a good default for a real topic), and any specific gotchas you know about that the guide should warn about.

A worked example

Section titled “A worked example”

Guide on CUDA streams and async memcpy. Audience: knows basic CUDA kernels, wants to overlap compute and transfer. Working knowledge depth, ~5 pages. Must cover: stream creation, async memcpy, events for synchronization, a copy-compute overlap example benchmarked against the serial version. Out of scope: multi-GPU, peer-to-peer. Usual pipeline, deploy when green, report URLs.

That request is actionable: it names the audience, the depth, the scope, and the proving run (the overlap benchmark).

What happens after you ask

Section titled “What happens after you ask”
  1. Outline first — for anything over ~6 pages, you get a page outline and can redirect it before a word is written. Redirecting an outline is cheap; redirecting a finished guide is not.
  2. Writing + verification — pages are written one concept at a time, and every runnable snippet is executed in the target environment. Anything that can’t be executed is marked untested and the page says exactly what wasn’t run and why.
  3. Checks and deploy — the site’s checks must pass (structure, build, links) before anything ships. Then it deploys and you get the live URLs, one per page.
  4. Maintenance — the weekly pass compares each guide’s targetEnv versions against current releases, checks external links, and flags anything stale. Guides rot; the maintenance pass is what keeps the rot visible instead of silent.

Reporting problems

Section titled “Reporting problems”

Found an error in a guide — a command that failed, a version that drifted, output that doesn’t match your run? Report it with the page URL, the command, and what happened. Guides are living documents; a report triggers a fix and a lastReviewed bump, not a shrug.