How-To Tutorial

Task-first writing that takes a reader from “I don’t know how” to “I did it” by organizing every decision around user goals, not system features.

How-To Tutorial

A how-to tutorial is a success contract with the reader. It opens with the task - not the history of the technology, not the theory of operation, not a context-setting paragraph about why this matters. The reader is already motivated; they arrived because they want to do something. Every word that precedes the first step is a word the reader skips.

Step numbers are sacred in this structure. Each numbered step contains exactly one action. Not one concept, not one paragraph of background, not two related actions that happen to be adjacent in the interface - one action. “Click Save” is a step. “Configure your settings and save” is two steps. When steps contain multiple actions, readers lose their place, skip one, and then blame themselves for the failure that follows.

The test of a how-to tutorial is functional: can a reader complete the task by following it? If the tutorial passes this test, it succeeds regardless of prose elegance. If it fails this test, no amount of clarity in the writing rescues it. This is the axis of quality that distinguishes how-to writing from all other expository forms.

Structural conventions

• Opens with a one-sentence statement of the task goal, not background context
• Each numbered step contains exactly one action
• Prerequisites listed before step one, not embedded inside steps
• Expected outcomes or confirmation signals follow steps where the result is not obvious
• Warnings and cautions precede the step they apply to, never follow it
• Ends with confirmation that the task is complete, not a summary of what was done

When to use

When the reader needs to accomplish a specific, bounded task with a verifiable outcome. Ideal for onboarding flows where a quick first success builds confidence, for troubleshooting guides where each resolution path is a distinct task, and for any procedure with a fixed sequence that must be followed in order.

When not to use

When the reader needs to understand how a system works rather than just operate it. Avoid when the subject is conceptual, when the correct procedure depends heavily on context the tutorial cannot anticipate, or when the goal is to build judgment and reasoning rather than execute a fixed sequence.

Pairs well with

technical-writer, instructional, friendly-mentor

Often confused with

diataxis-explanation: A Diataxis explanation is designed to build understanding - it answers “how does this work?” A how-to tutorial is designed to produce a completed action - it answers “how do I do this?” The distinction is functional: explanations serve comprehension; tutorials serve task completion. The same subject can yield two completely different documents depending on which goal governs the writing.

Instruction

Write as a how-to tutorial. The very first line states the task goal in one sentence. List any
prerequisites before step one. Number every step and put exactly one action in each step - not
one paragraph, not one concept, one action. Where the result of a step is not obvious, add a
brief expected-outcome note after the step. Put warnings before the step they apply to. Close
with a one-sentence confirmation that the task is now complete. Do not add background context,
explanatory asides, or section headers that delay the steps.

Related

Pairs well with

Technical Writer, Instructional, Friendly Mentor

Avoid with

Columnist, Devotional Reflection, Reverent

Often confused with

Diataxis Explanation

Examples

Should we adopt async-first standups?

How to roll out an async standup in your team

This guide walks a team lead through replacing a synchronous daily standup with an async update across four timezones. It is written for a lead running an 11-person engineering team distributed across US Pacific, US Eastern, UK, and India.

Prerequisites

Before you start, confirm the following:

• Your team has a shared Slack workspace (or equivalent) where you can create a dedicated channel.
• You have a recurring sync meeting slot you can repurpose. You will not delete it - you will reuse the time.
• You have at least two weeks of attendance data showing the cost of the current schedule. This makes the case if anyone resists.
• Your manager is informed. Async standups are not controversial, but they look like a meeting being cancelled, and that is a thing managers like to know.

Steps

1. Create the channel

Create #team-standup in Slack. Set the channel description to: “Daily async standup. Post by 10am your local time. Three fields: Shipped, In progress, Blocked or at risk.”

2. Pin the template

Pin a message to the channel with the exact three-field template:

Shipped: [what merged or shipped in the last 24h]
In progress: [what you are working on today]
Blocked or at risk: [what is stuck, @mention who can unblock]

A pinned template removes the need for anyone to remember the format.

3. Announce the 30-day trial

Post in the team channel that the team will run async standups for 30 days, with a revert option. Name the start date. Name the success criteria: blocker resolution time, channel engagement, team survey.

4. Cancel the daily sync

Cancel the recurring 9am Pacific standup on the calendar. Do not just stop attending. Cancelling the invite signals the change is real.

5. Create the Thursday working session

Add a recurring 60-minute Thursday meeting at a time that works for all four timezones. This is your new sync slot. Use it for discussion that needs real-time exchange.

6. Post first, ask others second

On day one, post your own update by 9am Pacific before anyone else. Modeling is faster than instructing.

7. @mention blockers explicitly

When you see a blocked item without an @mention, reply in thread and ask who owns it. Do this for the first week. After that the pattern is self-sustaining.

Confirming it worked

After 30 days, check three things:

• Median time from “Blocked” post to first reply from the unblocker. Target: under 2 hours during overlap windows.
• Number of team members posting at least 4 of 5 weekdays. Target: 9 of 11.
• A short survey: “Do you have more or less context on what your teammates are doing than 30 days ago?”

If two of three are positive, keep the change. If two of three are negative, revert and write up what you learned.

How to start a morning routine

How to Build a 30-Day Morning Routine Starting Tomorrow

This tutorial walks you through setting up a morning routine you can run for thirty days starting tomorrow. By the end, you will have a defined sequence, a tracking method, and a clear signal for whether it is working.

Prerequisites

Before you start, make sure you have:

• A consistent wake time you can hit five days a week, give or take fifteen minutes.
• A place to keep your phone overnight that is not within arm’s reach of the bed.
• One pen and a notebook, or a simple notes app you only open after the routine is done.
• A glass and access to water in your kitchen.
• Twenty to forty-five minutes available between waking and the first scheduled demand of your day. If you do not have this window, the first step is to make it by setting the alarm earlier or moving the first demand later.

Steps

1. Pick your wake time tonight, not tomorrow morning.

Decide now what time you will wake up. Set the alarm before you go to bed. Do not negotiate with this number in the morning.

2. Move the phone before sleep.

Place your phone in a room you have to walk to. The bathroom counter, the kitchen, or a hallway shelf all work. The goal is to make checking it require a deliberate movement, not a reach.

3. On waking, do not check the phone. Get out of bed.

This is the hardest step and the one that gates everything else. If you do this one thing for thirty days, the rest of the routine is easier to install. If you skip this step, the rest of the routine will not survive.

4. Drink a full glass of water.

Pour it. Drink it. This takes about ninety seconds and gives the body a clear signal that the day has started.

5. Get light on your face.

Step outside for two minutes, or open a curtain and stand near the window. Cloudy days count. The point is the light signal to your circadian system, not the temperature.

6. Do one movement activity for ten to fifteen minutes.

A walk around the block, a stretch sequence you already know, a few sets of pushups, or any short exercise. Pick one thing in advance. Do not decide in the moment.

7. Do one quiet activity for ten to twenty minutes.

Read a few pages, write half a page in a journal, plan the day on paper, sit with coffee and no screen, or pray. One thing, chosen in advance.

8. End the routine by checking the phone deliberately, not reactively.

Sit down. Open the phone. Do a single pass through messages and calendar. Close it. This converts “checking the phone” from a reflex into a step.

9. Mark the day on a paper tracker.

A simple grid of thirty boxes on a printed sheet, taped to a wall you walk past. Mark an X each day you complete the routine. The visible chain becomes its own incentive.

10. Review on day 7, day 14, and day 30.

At each checkpoint, ask: which steps are sticking, which are skipping, and which need to be shortened or removed.

How to know it worked

You have succeeded if, at day 30, you can answer yes to at least three of these:

• You completed the routine on at least 22 of the 30 days.
• Your first ten minutes of the day no longer involve the phone.
• You can describe the routine from memory without checking these instructions.
• You felt different on the days you did the routine compared to the days you skipped it.
• You want to keep going.

If you can say yes to fewer than three, the routine is too long. Cut it in half and run another thirty days.

How to choose between Postgres and DynamoDB for a new service

How-To Tutorial on: Choosing between Postgres and DynamoDB

This tutorial walks you through making a defensible storage choice between Postgres and DynamoDB for a new service, using the Lattice Notify notification system as the worked example. By the end, you will have produced a written recommendation ready to present at the Wednesday 2pm architecture meeting and committed to the team by Friday.

Prerequisites

Before you start, make sure you have:

• A clear definition of the new service and its expected access pattern (Lattice Notify: write-heavy, key-lookup by user_id, time-ordered).
• Launch volume estimate and a 12-month growth scenario, with a probability for that scenario (500K events/day at launch; 5M at 10x; 60% probability per the CRO).
• The current on-call rotation size and current familiarity with each candidate (4-person rotation; familiar with Postgres, unfamiliar with DynamoDB).
• Knowledge of which other systems will need to read or join against this service’s data (billing, analytics, product UI - all on Postgres).
• Empty document at docs/decisions/2026-05-15-notification-storage.md.

Steps

1. Write the access pattern in one sentence.

Open the decision doc. Type the actual access pattern, not a category. For Lattice Notify: “Write a notification record per event, read recent notifications for a given user_id ordered by timestamp.”

2. List every other system that will read or join against this data.

Bullet list. For Lattice Notify: billing (joins user, plan, notification volume), analytics dashboards (joins workspace, user, event), product UI (reads notifications by user_id). All currently on Postgres.

3. Look up your current on-call rotation and their database familiarity.

Find the rotation roster. Confirm how many engineers are on it and which databases they have operated in production. For Lattice Notify: 4 engineers, all fluent in Postgres, none have run DynamoDB in production.

4. Write the launch volume and 10x scenario with the probability of the 10x case.

One line each. “Launch: 500K events/day. 10x scenario: 5M events/day in 12 months. Probability: 60%.”

Warning: do not skip the probability. A growth scenario without a probability is a guess. Get the number from your PM, your CRO, or your sales lead, not from your own estimate.

5. Score each option against five criteria.

Use this table format. Score each option on access-pattern fit, team familiarity, operational surface area, cross-system query cost, and 10x growth behavior. Use simple labels: excellent, good, adequate, poor.

Criterion	Postgres	DynamoDB
Access-pattern fit	Adequate	Excellent
Team familiarity	Excellent	Poor
Operational surface area	No change	Doubled
Cross-system query cost	Native SQL	Application code
10x growth behavior	Sharding project required	Native

6. Calculate the expected operational cost of each option using the probability.

For each option, estimate the cost if the 10x scenario hits and the cost if it does not. Multiply by the probability and sum. Round to weeks of engineering work. For Lattice Notify: DynamoDB-from-day-one costs roughly 40-50 engineer-weeks of operational drag over twelve months in either scenario. Postgres-with-deferred-trigger costs roughly 0 in the no-Slack-deal case and roughly 3-6 weeks of migration if the deal lands.

7. Name the load-bearing constraint.

Pick the one criterion that, if violated, makes the option unsafe regardless of other scores. For Lattice Notify: on-call rotation operational safety. This converts the decision from “which is better” to “which is acceptable.”

8. Write the recommendation in one paragraph.

Lead with the choice and the trigger condition, if any. For Lattice Notify: “Ship on Postgres with a queue. Pre-commit to a DynamoDB migration if real volume crosses 2M events/day on a 30-day rolling average.”

9. Schedule the architecture meeting and circulate the doc 24 hours in advance.

Calendar invite, doc link in description. For Lattice Notify: Wednesday 2pm Pacific. Send the doc Tuesday by 2pm. Notify Ana, Marcus, Priya, and the four-person on-call rotation.

10. Run the meeting. Capture objections in the doc.

Take live notes inline. If the recommendation survives the meeting, mark the decision committed and assign owners. If a load-bearing assumption is challenged, defer the decision by 24 hours and re-run the math.

11. Commit the decision to the team channel by Friday morning.

Single message in the engineering channel. Include the recommendation, the trigger condition, the owner, and a link to the decision doc. Sprint planning runs Friday 2pm against this decision.

How to know it worked

You have succeeded if, at sprint planning Friday afternoon:

• The team can name the choice without checking the doc.
• The trigger condition (if any) is recorded with a defined threshold and owner.
• Sprint planning produces concrete tasks against the chosen storage path.
• No engineer can identify a load-bearing criterion that was not considered.

If any of these fail, the decision is not yet shippable. Reopen the doc and re-run from step 5.

Appears in diff-pairs

• how-to-tutorial vs narrative-case-study (varies style)