When publishing code samples/notebooks, write documentation that is (a) decision-first, (b) API-current, and (c) goal-focused.
1) Add “when to use” differentiation for competing interfaces
- If the SDK offers multiple runners/tools/strategies, include a comparison section with concrete decision criteria (e.g., orchestration model, result granularity/latency, dataset size, limits/caps, and phases).
Example (template for evaluation runners):
| Runner | Orchestration | Results shape | Best for |
|---|---|---|---|
| OnDemandEvaluationDatasetRunner | invoke → wait → evaluate (client-side) | per-scenario detail immediately | CI/dev iteration, small datasets |
| BatchEvaluationRunner | invoke → wait → submit → poll (service-side) | aggregate per-evaluator; detailed sessions in logs | baseline runs, large datasets |
2) Remove deprecated/legacy APIs and align naming to modern guidance
- Don’t keep “legacy” client approaches in parallel with recommended APIs.
- Rename notebooks/files so the name encodes the difference (e.g.,
*-inbuilt-strategy vs *-override-strategy) and ensure the content uses current, supported APIs.
3) Keep the notebook centered on the teaching objective
- Extract heavy or non-core setup (e.g., agent deployment/build/push/runtime creation) into scripts/utilities.
- In the notebook, start with a short description of the goal, then show only the minimal setup needed to demonstrate the target technique (e.g., evaluation loop/batch polling, memory hook behavior).
Follow-up checklist
- Does each alternative include a “when to use” table/criteria?
- Are there any deprecated interfaces left in the sample?
- Is the notebook’s flow dominated by the concept being taught (not deployment plumbing)?
- Do filenames/notebook titles reflect the actual strategy/interface used?