Tutorials
Step-by-step learning content that walks a consumer from zero to a working integration around a specific use case. Tutorials sit between the bare quickstart (one-call hello world) and the full reference (everything you could call); their job is to teach how the pieces compose. A healthy tutorials surface covers the canonical workflows for the API and is the second-most-visited area of a portal after the reference.
Also known as: Tutorial, Guides, Learning, Walkthroughs, How-To
Example
Standards
- Schema.org schema.org HowTo
- Schema.org schema.org LearningResource
- Schema.org schema.org Course
- CommonMark CommonMark 0.31
- OpenAPI Initiative Arazzo Specification 1.0.1
OpenAPI Expression
-
x-codeSamples(Redoc / Redocly vendor extension) — Per-operation code samples are often lifted directly from tutorial content. -
tags[].externalDocs(OpenAPI 3.x) — Tutorial sets are commonly linked from per-tag external docs.
Risk & Compliance
Security: Tutorials are read and copied far more than reference docs; an insecure pattern in a tutorial (skipped TLS verification, hardcoded admin tokens, weak input handling) propagates into production code at scale. Treat tutorials as production-quality code and lint them with the same governance rules as samples.
Tools
- MDX — Markdown with interactive components for tutorials (MIT)
- Docusaurus — Docs site with tutorial layouts (MIT)
- Jupyter Book — Executable-notebook tutorials (BSD-3-Clause)
- Arazzo — Machine-readable workflow descriptions that pair with tutorials
Suggested Metrics
tutorial_completion_rate— Share of readers who reach the final step of a tutorial.tutorial_to_first_call— Time from opening a tutorial to making the first real API call.tutorial_freshness_days— Days since each tutorial was last validated against the live API.copy_button_click_rate— Engagement with copyable snippets — a proxy for tutorial usefulness.
Example Implementations
- Twilio — Long-running tutorial library covering messaging, voice, and video flows.
- Stripe — Use-case tutorials per payment method and integration pattern.
- GitHub — Multi-step guides covering common platform workflows.
Related Properties
Tags
- Onboarding
- Documentation
- Learning