Make Program Tutorial

Inputs to Collect (ask if missing)

• Target topic:
  • Library/SDK name (version optional), or
  • The specific functions/classes/modules to cover
• Target audience (beginner vs experienced) and target language/runtime (Python/JS/etc.)
• Execution environment assumptions (OS, GPU/CPU, required services)
• Output directory (default:

  <workspace>/tmp/tutorials/<tutorial-name>

  ; if the user specifies a dir, prefer the user-provided one)
• Any constraints (no network, no secrets, offline-only, time budget, etc.)

Outputs (what to produce)

Default output directory:

• <workspace>/tmp/tutorials/<tutorial-name>

Create the output directory with:

• tut-<what>.md

• scripts/

  (end-to-end runnable scripts for this tutorial)

• inputs/

  (small tutorial-specific inputs, if applicable)

• outputs/

  (tutorial-specific outputs, if applicable)

In

tut-<what>.md

, include a YAML front matter block that records the runtime environment at the time the tutorial is created, including the base git commit hash of the workspace/repo.

Always provide end-to-end runnable scripts under

scripts/

and have the tutorial instruct users to run those scripts (instead of embedding long code blocks in the doc).

Workflow

1) Identify the canonical sources

• Determine the authoritative docs/repo for the target API/library.
• Do not pin versions unless the user asks for it.
• If the tutorial is for a set of functions/classes in a local repo, read the source and identify:
  • Import paths, initialization patterns, and required config
  • Any side effects (I/O, network calls, GPU usage)

2) Choose a minimal “happy path”

• Define the smallest end-to-end example that demonstrates value:
  • Inputs → processing → outputs
• Prefer real inputs if available; otherwise synthesize minimal inputs that satisfy the API contract.
• Record the exact commands used to run the example and the resulting artifacts.

3) Implement end-to-end scripts in

scripts/

• Create one or more runnable scripts under

  scripts/

  that demonstrate the full “happy path”.
• Scripts must:
  • Read inputs from

    inputs/

    (prefer real files; synthesize only if necessary and explain why)
  • Write artifacts to

    outputs/

  • Print a concise success summary (paths written, key shapes/counts)
• Keep scripts as small as practical but runnable; prefer a single

  scripts/run.py

  unless multiple steps are clearer.

4) Write

tut-<what>.md

(tutorial doc)

Choose a short, specific

<what>

(e.g.,

tut-httpx-basics.md

,

tut-onnxruntime-infer.md

).

Follow the template in

templates/tut-what.md

:

• Start with a concrete Question (“How do I … using …?”).
• Add a Prerequisites checklist (do not teach setup in detail; assume prerequisites are already met).
• Add an Implementation Idea section with a short, high-level approach.
• Add Critical Example Code that is copy/pasteable and heavily commented to explain the usage step-by-step.
• Add Input and Output sections documenting the contract and showing representative examples (requests/responses, logs, artifacts).
• Keep code blocks self-contained and small; for the full implementation, point to

  scripts/...

  and show the exact command(s) to run.
• Add YAML front matter capturing:

  • created_at

    (ISO8601),

    tutorial_name

    ,

    topic

  • base_commit

    (workspace git commit hash)

  • runtime

    (OS, CPU/GPU, Python version, key package versions if relevant)

5) Include tutorial inputs/outputs

• Place tutorial-ready inputs under

  inputs/

  .
• Place tutorial outputs under

  outputs/

  .
• Keep them minimal and (when relevant) redistributable.

6) Add troubleshooting and verification

• Add a short “Troubleshooting” section with the top failure modes:
  • Missing deps, version mismatches, device selection issues, path errors
• Add a “Verification” section:
  • Exactly how to confirm outputs are correct (shapes, counts, sample prints, checksums)

Guardrails

• Do not include secrets/tokens or require users to paste credentials into the tutorial.
• Avoid “works on my machine” ambiguity: always include the exact commands and expected outputs/paths.
• Prefer stable, minimal dependencies; if multiple installation methods exist, pick one and mention alternatives briefly.