Recipe: mentor-encouraging-tutorial
A composition of Friendly Mentor voice, Encouraging tone, How-To Tutorial style, and README format. Used for onboarding documentation aimed at early-career engineers who are doing each thing for the first time.
When to use
Section titled “When to use”Use this recipe when the reader is an engineer doing something for the first time and the obstacle is as much confidence as it is information. It fits onboarding READMEs, new-hire setup guides, first-contribution walkthroughs, and any procedural doc where a quick first success is more valuable than completeness. The recipe assumes the reader is capable but new, has the patience for short steps, and benefits from being told which moments usually feel hard.
When to use something else
Section titled “When to use something else”If the audience is an experienced engineer who wants the canonical procedure without scaffolding, swap Friendly Mentor for Technical Writer and Encouraging for Matter of Fact so the doc reads as a reference, not a lesson. If the goal is to explain how a system works rather than to walk through a task, reach for Diataxis Explanation instead of How-To Tutorial. If the document needs to live as a long-form lookup surface for many sub-procedures, use Technical Reference rather than README, which is built for first-time visitors and breaks down as it grows.
Composition
Section titled “Composition”| Axis | Entry | Why |
|---|---|---|
| Voice | Friendly Mentor | Treats the reader as capable but new, scaffolds new concepts from familiar ones, and names the sticking points out loud rather than pretending they are not there. This is the voice of the best onboarding buddy a new hire ever had. |
| Tone | Encouraging | The obstacle for a first-timer is often belief that they can do this at all. Encouraging tone names the real difficulty, then expresses genuine confidence in the reader’s ability to get through it, without lapsing into cheerleading. |
| Style | How-To Tutorial | The reader arrived to complete a specific task. Prerequisites up front, one action per numbered step, a clear success signal at the end. The structure protects the reader from getting lost in their own first attempt. |
| Format | README | The doc is the front door of a procedure. It is scanned before it is read, lives in a repo or a wiki, and uses code blocks, H2 sections, and short prose. It assumes the reader will skim first and follow along on a second pass. |
Worked examples on this recipe
Section titled “Worked examples on this recipe”- Your first pull request
- Setting up your development environment
- Writing your first test