Tech Tutorial

---
name: tech-tutorial
description: Plans, drafts, and refines technical tutorials for developers. Use when writing step-by-step guides or getting-started walkthroughs backed by working code.
globs: "**/*.md"
alwaysApply: false
category: artifact-generation
tags:
- tutorial
- technical-writing
- code-examples
- developer-docs
- getting-started
tools: []
complexity: medium
model_hint: standard
estimated_tokens: 2800
progressive_loading: true
modules:
- modules/outline-structure.md
- modules/code-examples.md
- modules/progressive-complexity.md
dependencies:
- scribe:slop-detector
---
# 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.
If you cannot answer the "what will they accomplish" question
in one sentence, the scope is too broad. If you cannot state
the thesis in one sentence, the tutorial is not ready to draft.

The audience size and read frequency feed the reader-time
budget (see `scribe:slop-detector` module `document-economy.md`).
A tutorial that 500 developers will read once is a 40-hour
reader-budget asset. Spend the writing time accordingly.

The tier decides what the draft may contain. When the request
names no reader, **ask, do not guess**: `scribe:slop-detector`
module `audience-targeting.md` carries the tier table and the
Socratic set.

A `newcomer` tutorial keeps the one path that works, end to
end. Alternatives, internals, and the reasons the obvious
approach fails are `expert` material. They go to
`docs/deep-dive/<topic>.md`, linked from the lead in one line
that names who the deep dive is for. Never delete them to hit
the tier. A tutorial that pauses to compare three approaches
has stopped moving the reader from cannot to can.

### Step 2: Outline

Load: `@modules/outline-structure.md`

Produce a section-by-section outline before drafting prose.
Each section entry must include a one-line description of what
the reader does or learns in that section.
See the outline module for the standard section order and
length targets per section type.

### Step 3: Draft Code Examples First

Load: `@modules/code-examples.md`

Write the code before the prose.
Each snippet must run against a real environment before it
appears in the tutorial.
Annotate only the non-obvious lines.
See the code examples module for formatting and error-handling rules.

### Step 4: Draft Prose Around the Code

Prose exists to explain what the code does and why.
Follow these rules:

- One paragraph per step: what to run, what it does, what to expect
- State the expected output after each command block
- Use second person ("you") consistently throughout
- Do not narrate what the reader will do next. Just present the next step

### Step 5: Build Complexity Gradually

Load: `@modules/progressive-complexity.md`

Start with the minimal working example.
Introduce variations and edge cases only after the baseline works.
See the progressive complexity module for the layering rules
and pacing guidance.

### Step 6: Slop Check

After drafting, run:

```
Skill(scribe:slop-detector)
```

Fix all tier-1 findings before proceeding.
Pay particular attention to:

- Tier-1 vocabulary slop (see `scribe:slop-detector` word lists)
- Tricolon adjective clusters ("fast, efficient, and reliable")
- Participial tail-loading (sentences ending with ", enabling ...")

### Step 7: Quality Gate

Verify the completed tutorial against this checklist:

Content:
- [ ] All code blocks tested and produce the stated output
- [ ] Prerequisites section lists exact versions where relevant
- [ ] Every step states the expected result
- [ ] Troubleshooting section covers at least two common failure modes

Sentence-level:
- [ ] No tier-1 slop words
- [ ] Em dash count is under 2 per 1000 words
- [ ] Bullet ratio is under 40%
- [ ] Line length wraps at 80 characters

Document-level (document-economy module):
- [ ] Thesis from Step 1 appears in the lead paragraph
- [ ] Thesis echoed at the close (and ideally mid-tutorial)
- [ ] No "in summary" section that re-lists what just happened
- [ ] No section opens by restating its heading

Audience (audience-targeting module):
- [ ] Tier declared in Step 1, asked for when it was unstated
- [ ] Every section serves that tier
- [ ] Off-tier detail extracted to a linked deep dive, not deleted

## Required TodoWrite Items

1. `tech-tutorial:scope-defined` - Audience, goal, and out-of-scope noted
2. `tech-tutorial:outline-approved` - Section outline confirmed
3. `tech-tutorial:code-tested` - All snippets verified against a real env
4. `tech-tutorial:prose-drafted` - Walkthrough text written
5. `tech-tutorial:slop-scanned` - Slop detector passed
6. `tech-tutorial:quality-verified` - Quality gate checklist cleared
7. `tech-tutorial:user-approved` - Final approval received

## Module Reference

- See `modules/outline-structure.md` for section order and length targets
- See `modules/code-examples.md` for snippet formatting and annotation rules
- See `modules/progressive-complexity.md` for pacing and layering guidance

## Integration with Other Skills

| Skill | When to Use |
|-------|-------------|
| scribe:slop-detector | After drafting, before approval |
| scribe:doc-generator | For companion API reference sections |
| scribe:style-learner | To match an existing tutorial voice |

## Exit Criteria

- Tutorial outline confirmed before drafting begins
- Audience tier declared before drafting, not after
- All code snippets tested in a real environment
- Slop score below 1.5 (clean)
- Off-tier content was moved to a linked deep dive rather than
  left in the reader's path or deleted
- Quality gate checklist passed
- User approval received