Tech Tutorial

Tech Tutorial

A good technical tutorial has one goal: move a reader from not knowing how to do something to being able to do it. That requires working code, concrete steps, and honest acknowledgment of where things go wrong. This skill guides you through outlining, drafting, and verifying a tutorial that meets that standard.

When To Use

• Writing a getting-started guide for a library, CLI tool, or API
• Creating a step-by-step walkthrough that readers follow at a terminal
• Explaining a technical concept through a hands-on exercise
• Producing a how-to that complements API reference documentation

When NOT To Use

• Generating API reference docs (use scribe:doc-generator)
• Cleaning up existing prose (use scribe:slop-detector)
• Producing high-level architecture overviews without runnable steps
• Writing conceptual essays without hands-on components

Methodology

Step 1: Scope and Audience

Before writing a single line, answer these questions:

• Who is this for? Declare a tier: newcomer, practitioner, expert, or a one-line persona. A tutorial defaults to newcomer; if it does not, say what it assumes instead
• How many readers? How often will each one read it?
• What will they build or accomplish by the end?
• What is the one sentence they must walk away with? (the thesis, not the topic)
• What is the single prerequisite the reader must have installed?
• What is explicitly out of scope?

Write these answers down as a header block in the draft.