Technical Tutorial Writing

A tutorial is a guided walk through a working system. The reader starts with nothing and ends with code that runs and does something interesting. The product's adoption depends on the quality of this walk; if the reader hits a wall in the first 20 minutes, they leave.

## Key Points

1. **Setup** — get the project skeleton in place. Single command if possible (`npx create-x-app my-project`). Then enter the directory.
2. **First runnable example** — a 10-line snippet that produces a result. The reader sees something happen. Confirms the setup is correct. Builds momentum.
3. **Add the next layer** — incrementally. Each section adds one concept, with the running code visible after each addition.
4. **Show what they built** — at the end, the reader sees the final working artifact. A web page, a command-line output, a deployed URL.
5. **Where to go next** — links to the next-level tutorial, the relevant reference docs, the community.
- **CI verification.** Every snippet in the tutorial runs in CI. Failing snippets block product releases.
- **Quarterly walk-through.** A non-author engineer follows the tutorial end-to-end. Where they hesitate is what to fix.
- **User feedback channel.** A "give feedback on this tutorial" button at the bottom. Read every submission.
- **Versioning.** Major product versions get major tutorial revisions. Old tutorials are archived, not deleted, with a banner pointing to the new one.

A tutorial is a guided walk through a working system. The reader starts with nothing and ends with code that runs and does something interesting. The product's adoption depends on the quality of this walk; if the reader hits a wall in the first 20 minutes, they leave.

Tutorials are not reference documentation. They are not API specs. They are not blog posts about your roadmap. They are step-by-step paths from "I want to try this" to "I have something working." The discipline of the form is rigorous.

The Reader at Minute Zero

Your reader at the moment they start the tutorial: they have just decided to try your product. They have not read your other docs. They have a terminal open and an editor open and limited patience. They want to see something work; if they see it, they will read more, share with their team, and become a customer.

Write for that reader. Not for the reader who already knows your domain. Not for the reader who has integrated five similar products before. Not for the reader who will read your full reference docs end-to-end.

Every assumption you make about prior knowledge is a customer you lose. Some assumptions are unavoidable (the reader knows their language); most are not.

The Promise

Open with a one-paragraph promise: at the end of this tutorial, the reader will have built X, learned Y, and be ready to do Z. The promise is concrete:

By the end of this tutorial you'll have a working web app that authenticates users, lets them upload images, and runs a basic image-classifier on each upload. You'll understand how to integrate the auth and storage SDKs into a small project and how to call the classifier model from server code. The tutorial takes about 25 minutes.

Bad promise: "Learn how to use our SDK." Worthless. The reader can't tell whether they want to do this.

The promise gives the reader the contract: in 25 minutes, here is what they get. They commit or they don't, but they're not surprised mid-way.

The Prerequisites

List prerequisites explicitly. Software they need installed (with versions). Accounts they need (with sign-up steps if relevant). Knowledge they need (with brief refreshers or links).

Be precise:

Prerequisites:

• Node.js 20 or later (node --version)
• A free account on example.com (sign up: https://...)
• 10 minutes of basic familiarity with HTTP requests

Bad prerequisites: "Some experience with JavaScript." Vague.

If the prerequisites are heavy, consider whether the tutorial is targeted at the right reader. A tutorial that requires four installations and two accounts before it begins has lost the reader's attention.

The Structure

A standard tutorial follows this arc:

1. Setup — get the project skeleton in place. Single command if possible (npx create-x-app my-project). Then enter the directory.
2. First runnable example — a 10-line snippet that produces a result. The reader sees something happen. Confirms the setup is correct. Builds momentum.
3. Add the next layer — incrementally. Each section adds one concept, with the running code visible after each addition.
4. Show what they built — at the end, the reader sees the final working artifact. A web page, a command-line output, a deployed URL.
5. Where to go next — links to the next-level tutorial, the relevant reference docs, the community.

Every section is self-checkpointed. The reader runs code at the end of every section and verifies it works. If the code at the end of section 2 doesn't work, they go back to fix section 2 — they don't push through into section 3 with broken code.

The Runnable Example

The single most important property of a tutorial: every code snippet runs. Copy-paste, hit enter, it works.

This is not aspirational. This is verified. The CI for the tutorial repository extracts every code snippet from the tutorial markdown and runs it. If the test fails, the tutorial doesn't ship.

Without this discipline, tutorials rot. The product evolves; the tutorial doesn't keep up; readers run snippets that error; trust is destroyed.

The runnable example also means: the reader doesn't have to context-switch to figure out what's missing. The full context for each snippet is visible. Imports are shown. Variables are defined. The reader runs each snippet independently and sees the same output the tutorial promised.

The "Aha" Moment

Build toward an "aha" moment. The point in the tutorial where the reader sees the value of the product, viscerally. Not in the abstract; in the running output.

For an SDK that does image classification, the aha moment is when the reader uploads a photo of their dog and the classifier returns "Labrador retriever, 0.94." The reader laughs. They share it. They tell their team.

For an auth SDK, the aha moment is when the reader logs in with their Google account and sees the protected page. For a database, it's when they query 10 million rows and the result returns instantly.

Design the tutorial to hit the aha moment in the first 15 minutes. The setup, the first example, the first useful query. The aha is the reason the reader will continue.

Voice

Tutorials are written in second person, present tense, active voice.

Now you'll add the auth SDK. Run npm install @example/auth. Then open src/app.tsx and add this import:

Not "the developer should now install the auth SDK." Not "the auth SDK is added by running..." Direct, instructional, present-tense.

The voice is friendly but not familiar. Pretend you are an experienced engineer pair-programming with a colleague who is new to this product. You are explaining as you go, occasionally pointing out a detail, occasionally noting a gotcha.

You are not a stand-up comedian. You are not a marketer. The voice serves the reader, not the brand.

The Gotchas

Anticipate where the reader will trip. Each section flags the common mistake:

Note: if you see "Permission denied" here, your API key probably doesn't have the images:write scope. Go back to the dashboard and check.

The gotcha note appears at the place where the gotcha will hit, not in a separate troubleshooting section at the end. By the time the reader has scrolled to a troubleshooting section, they've already given up.

Maintenance Discipline

Tutorials rot. The product changes; the tutorial breaks. The maintenance discipline:

• CI verification. Every snippet in the tutorial runs in CI. Failing snippets block product releases.
• Quarterly walk-through. A non-author engineer follows the tutorial end-to-end. Where they hesitate is what to fix.
• User feedback channel. A "give feedback on this tutorial" button at the bottom. Read every submission.
• Versioning. Major product versions get major tutorial revisions. Old tutorials are archived, not deleted, with a banner pointing to the new one.

Untouched tutorials lose customers silently. The reader runs the broken example, gives up, and you never hear about it.

The Tutorial vs. Reference Distinction

Tutorials walk; reference describes. Confusing the two damages both.

A tutorial that pivots into reference material — "and here are all 47 options for the function we just used" — kills the momentum of the walk. The reader is here to learn, not to memorize. Cut the reference; link to it.

Reference docs that pretend to be tutorials — "this section will introduce you to the Foo API" — leave the reader with no working code. Reference is for the reader who already knows what they want and just needs to look up the syntax.

Each tutorial has a companion reference (the API docs, the SDK reference). The tutorial points to the reference when the reader graduates from "guided walk" to "I know what I'm doing."

Anti-Patterns

No promise. Tutorial opens with marketing copy. Reader can't tell what they'll have at the end.

Snippets that don't run. The reader copy-pastes, hits an error, gives up. CI verification prevents this.

Wall of text before the first runnable example. The reader scrolls past it. Get to running code in the first three minutes.

Tutorial doubles as reference. "And here are all the options for this function." The walk is interrupted. Cut and link.

Author voice. "When I built this, I learned that..." First-person digressions break the second-person instructional voice.

No troubleshooting at the trip points. Errors get raised in a separate section at the bottom. By the time the reader gets there, they've given up. Inline.