Skip to content
Writing Style Library

Instructional

Patient, structured teaching that measures its own success by whether the reader can do the thing - not by how much it explains.

Instructional

Section titled “Instructional”

Instructional tone exists to transfer capability, not to display knowledge. Every sentence earns its place by moving the reader closer to being able to do the thing. Steps are numbered. Terms are defined at first use. The structure is visible because visibility is itself a form of respect for the reader’s time and cognitive load.

The register is neither warm nor cold - it is focused. Instructional tone does not reassure the reader that they can do it. It clears the path so they can. The emotional tenor is the neutral competence of a skilled guide: present, careful, and entirely oriented toward the reader’s success rather than the writer’s expression.

What separates instructional from merely technical is pacing. Instructional tone does not assume context; it builds it. It anticipates the point of confusion and names it before the reader hits it. The measure of a well-instructional piece is not its completeness but its usability - a reader who finishes it should be able to do what the piece set out to teach.

Markers

Section titled “Markers”
  • Numbered steps, each expressing exactly one action
  • Terms defined in the same sentence or clause where they first appear
  • Explicit orientation before transitions: “Before you do X, make sure Y is complete”
  • No reassurances or motivational asides - only forward movement
  • Second person used to assign action to the reader, not to the writer
  • Anticipated failure points named and addressed inline: “If you see [error], it means…”

When to use

Section titled “When to use”

Setup and installation documentation, step-by-step tutorials, onboarding flows that must transfer real skill, technical reference material walking through a process, and any context where the reader needs to do something specific and get it right.

When not to use

Section titled “When not to use”

Conceptual overviews not tied to a specific procedure, executive summaries, persuasive communication, content for expert audiences who need inference latitude rather than hand-holding, and emotional or high-stakes interpersonal communication.

Pairs well with

Section titled “Pairs well with”

technical-writer, friendly-mentor, how-to-tutorial

Often confused with

Section titled “Often confused with”

encouraging: Encouraging tone validates effort and names capability - it is about activating the reader’s belief that they can succeed. Instructional tone does not validate or motivate; it clears obstacles. An instructional piece succeeds by making the path so clear that confidence is irrelevant. Encouraging is about the reader’s relationship to the difficulty; instructional is about removing the difficulty from the reader’s path.

Instruction

Section titled “Instruction”
Write in an instructional tone. Your only goal is the reader's ability to do the thing when
they are done. Number every step; each step should express one action only. Define any term
the first time you use it, in the same sentence if possible. Anticipate confusion and address
it before the reader reaches it. No reassurances, no motivational asides - every sentence
should either advance the procedure or clarify what is happening. Use second person to keep
action with the reader. Measure each sentence by asking: does this move the reader closer to
being able to do it?
Section titled “Related”

Pairs well with

Section titled “Pairs well with”

Technical Writer, Friendly Mentor, How-To Tutorial

Avoid with

Section titled “Avoid with”

Playful, Pastoral

Often confused with

Section titled “Often confused with”

Encouraging

Examples

Section titled “Examples”

How the async standup works, starting Monday

Section titled “How the async standup works, starting Monday”

Starting Monday, we are running a 30-day trial of async standups in place of the 9am Pacific sync meeting. This guide explains what is changing, what you need to do, and how to recognize a well-formed update. Read it once, then refer back as needed.

What is changing

Section titled “What is changing”

Sync standup (the daily 9am Pacific call) is paused for 30 days.

Async standup is a written daily update posted in #team-standup. “Async” here means there is no shared meeting time - each engineer posts on their own schedule within a window.

Working session is a new 60-minute Thursday slot in the same calendar block. This is for real coordination work, not status. Agenda will be posted Wednesday.

What you need to do

Section titled “What you need to do”
  1. Post your update in #team-standup by 10am local time each working day. Local means your local time, not Pacific. If you are in Bengaluru and start work at 9am IST, you post by 10am IST.
  2. Use the three-field format. Each update has exactly three sections:
    • Shipped: What you completed since your last update. Link the PR or doc.
    • In progress: What you are working on today. One or two items, not a backlog dump.
    • Blocked or at risk: Anything that needs help. If empty, write “None.”
  3. @mention the unblocker on every blocker. A blocker without a name attached is not actionable. If you are not sure who to mention, mention your lead and they will route it.
  4. Read the channel once per day. You do not need to read every update, but scan for @mentions of you and for blockers in your area.

What a good update looks like

Section titled “What a good update looks like”

Shipped: Auth retry logic merged (#4412). In progress: Migrating session cache to Redis, expect PR by EOD. Blocked: Need staging access for new region - @priya.

That is a complete update. Three lines, specific, one named owner on the blocker.

What we are measuring

Section titled “What we are measuring”

At day 30 we will review three things: blocker resolution time, participation rate across timezones, and whether the Thursday session is delivering coordination value. We will decide together whether to keep the format, revert, or adjust.

Questions go in the thread under Monday’s kickoff post.