Instructional

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

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

• 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

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

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

technical-writer, friendly-mentor, procedural

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.

Tells

• 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 assigns the action to the reader, not to the writer
• Anticipated failure points named and addressed inline (“if you see [error], it means…”)

Anti-patterns

• Adding motivational asides or validating the reader’s effort between steps - That is encouraging, which activates belief; instructional tone clears obstacles so well that confidence is irrelevant, and the asides slow the procedure they interrupt.
• Explaining the topic to show command of it rather than to enable the action - Instructional tone transfers capability, it does not display knowledge; every sentence should move the reader closer to doing the thing, not demonstrate what the writer knows.
• Assuming context the reader does not have and skipping the step that builds it - What separates instructional from merely technical is pacing; it builds context rather than assuming it, and a gap the reader cannot bridge breaks the transfer of capability.

Failure modes

• Over-explains into condescending hand-holding, spelling out what any reader already knows - Calibrate to the stated audience and cut steps that explain the obvious; the measure is usability, not completeness, and over-instruction wastes the reader’s time as surely as under-instruction strands them.
• Over-structures into mechanical rigidity, where the scaffolding obscures the actual task - Keep the structure in service of the doing; if the numbering, sub-steps, and caveats have grown denser than the procedure they describe, simplify until a reader could follow it on the first pass.

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?

Related

Pairs well with

Technical Writer, Friendly Mentor, Procedural

Avoid with

Playful, Pastoral

Often confused with

Encouraging

Examples

Should we adopt async-first standups?

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

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

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

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

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.

How to start a morning routine

This guide walks you through starting a morning routine in five steps. Read all five before beginning. Each step builds on the previous one.

Step 1: Establish your baseline.

For three mornings, write down what you currently do, in order, with timestamps. Include phone use. Do not change anything yet. The goal is data, not progress. A “baseline” is simply a record of your existing behavior; without it, you cannot see what is changing.

Step 2: Identify your fixed points.

A fixed point is a time you cannot move. Examples: work starts at 9am, kids need to leave by 8:15am, your partner showers at 7:00am. List your fixed points. Subtract preparation time (commute, getting dressed, breakfast) from the earliest fixed point. The result is the latest your routine can end. Working backward from that time, decide how long your routine can be. For most people, 20 to 45 minutes is realistic.

Step 3: Choose one anchor action.

An anchor action is the first deliberate thing you do after waking. It should require no decisions and minimal setup. Common anchors: drinking a full glass of water, opening a curtain, stepping outside for two minutes. Do not choose more than one anchor in week one. Adherence drops sharply when the routine has too many starting elements.

Step 4: Define a phone rule.

A phone rule is a clear, binary boundary: when you may first check your phone. Example rules: “after my anchor action,” “after I am dressed,” “at 7:30am.” Pick one. Move the phone out of the bedroom if necessary. The rule is not about willpower; it is about removing the decision.

Step 5: Run a two-week pilot.

Do steps 3 and 4 only, for fourteen days. At the end of week two, review. If you held the routine on 10 or more days, you may add a second element (reading, exercise, journaling). If you held it on fewer than 10 days, do not add anything. Make the existing routine smaller until it holds, then build from there.

How to choose between Postgres and DynamoDB for a new service

Instructional on: Choosing between Postgres and DynamoDB

How to run the Postgres-vs-DynamoDB decision at the Wednesday 2pm architecture meeting.

Before you start, make sure all attendees (Ana, Marcus, Priya, and the 4-person on-call rotation) have read both option writeups and the load-test results. If any reviewer has not, postpone the meeting; you cannot run this procedure with cold readers.

1. Open with the decision constraint. State that Priya needs an answer by Friday so the next sprint can be planned. This frames the meeting as “make the call” rather than “explore the question.”

2. State the two options exactly. Option A: ship on Postgres, add a notifications schema and a queue. Option B: add DynamoDB as a second store for notification events. Write both on the whiteboard. Do not add a third option unless someone proposes one with a concrete writeup; “what about Kafka” is not an option, it is a derailment.

3. Walk through the load model. Confirm the launch number (500K events/day) and the 10x scenario (5M events/day if the Slack partnership lands within 12 months). If anyone disputes the numbers, resolve that before continuing; you cannot evaluate the options against a contested baseline.

4. Have Marcus present the DynamoDB case in 5 minutes, then Ana the Postgres case in 5 minutes. Time each presentation. If a presenter runs over, stop them; the disciplined version of the case is the one the room can evaluate.

5. Ask each on-call engineer the same question, in order: “What does adding a second database do to your week?” Write the answers on the board verbatim. This is the operational input that is usually missing from architecture decisions.

6. Identify the decision thresholds. Specifically: at what event volume does Postgres stop being sufficient? At what point in the partnership timeline does the 10x scenario become real rather than hypothetical? Write both numbers.

7. Take a straw poll. If it is unanimous, confirm the decision. If it is split, run one more round of discussion focused only on the strongest objection to the leading option. Do not run a third round.

8. Name the decision, the owner, and the next-action item. Example: “We are shipping on Postgres. Marcus owns the DynamoDB migration design doc. Ana owns the schema review. We revisit at 3M events/day or partnership signing, whichever comes first.”

9. Send the meeting notes to Priya by end of day Wednesday so she has them before the Friday sprint planning.

If the meeting cannot reach a decision in 60 minutes, do not extend it. Schedule a 30-minute follow-up for Thursday morning with only Ana, Marcus, and Priya, and use Wednesday’s remaining time to narrow the disagreement to a single resolvable question.

Telling stakeholders a committed feature is being cut this quarter

Here is what you need to know about the Insights delivery, and what steps follow from it.

Insights - the in-app analytics dashboard scheduled for Q3 - is moving to Q1 of next year. The reason is a mandatory billing-system migration (a required infrastructure upgrade to meet updated payment-processing compliance requirements) that ran significantly over its allocated duration and consumed the engineering capacity set aside for Insights. Shipping in Q3 would have meant delivering the data pipeline without the dashboard interface - the part you would use. We chose not to do that.

Before you update your own plans, it helps to understand what happened to the timeline. The billing migration’s integration surface turned out to be substantially larger than the pre-migration audit indicated. We did not surface that risk to stakeholders early enough; that gap is being addressed in how we scope and track migration work going forward. If you need to explain the slip to your own teams or customers, the accurate framing is: a mandatory infrastructure requirement expanded unexpectedly and consumed the capacity reserved for Insights. Scope creep on a compliance dependency is the cause, not a reprioritization of Insights itself.

Before the end of September, you will receive a CSV export of the underlying analytics data - the same data set that the Insights dashboard will surface in Q1. To begin using it, download the file from the link in the delivery email, open it in your preferred analysis tool (a spreadsheet, a BI platform, or anything that reads CSV), and note that the first row is a header row and the default date range covers the current quarter.

Insights ships Q1. A confirmed date follows as soon as Q4 planning closes.

Getting a new engineer productive in their first two weeks

Getting Priya productive in two weeks requires you to front-load access and context, then shift quickly to doing.

Week one: foundation

1. Before her first stand-up, give Priya credentials for every system she needs: the version-control host, the deployment pipeline, the ticket tracker, and the on-call tool. If any access requires a request queue - a system where permissions must be approved by a separate team - submit the request the Friday before she starts. Delays here block everything else in week one.

2. On day one, run a ninety-minute codebase walkthrough. Cover the service boundary - the edge at which your team’s ownership ends and another team’s begins - mapping which services your team owns and where the handoffs to other teams sit.

3. On day two, pair with her to locate two things in the codebase: where a change she could own lives, and what the deploy path looks like from commit to production.

Week two: shipping

4. Before week two begins, pick the change she will ship. It must be real - not a tutorial exercise - and scoped to a single file or function. If completing it requires understanding more than two service boundaries, it is too large for this slot.

5. Pair through the entire cycle: writing the code, opening the pull request, responding to review, and watching the deploy. Do not hand off during review.

6. After the change ships, name the on-call rotation explicitly: when her first shift starts, who to page if something breaks, and what the escalation path - the ordered list of contacts to try in sequence - looks like.

Belonging follows from step six. Once Priya has shipped real work and knows who holds what, she has the same operating facts as the rest of the team.

Writing to thank a mentor who shaped your career

Dear Dana,

Before reading this letter in full, know why you are receiving it: I recently did something I did not know I had learned, and I traced it back to you.

Here is what I need you to understand, in the order it happened.

1. In the autumn of my first year on your team, you nominated me to lead the Radcliffe platform migration - a project that required judgment on decisions I had never made before. You told me I was ready. I disagreed. You were right.

2. For those eight weeks, you stayed available without taking over. When I hit the dependency handoff problem in week four - the one where my team and the receiving team had made incompatible assumptions - you did not solve it. You asked two questions and left. I resolved it the same day.

3. What you were practicing, without labeling it, was a specific pattern: place someone in the condition for success, then get out of their path while remaining within reach. That pattern requires patience that is invisible because it looks like ordinary absence.

Before you read the next step as routine news, note that it is the reason this letter exists.

4. Last month I put a direct report forward for a project she did not feel ready for. When she hit her version of week four, I felt the pull to step in and fix it. I stopped. I asked two questions. I left.

She solved it before the end of the day.

You can now see why I am writing. What you gave me a decade ago was not belief in my potential. It was a transferable procedure. I only recognized it when I ran it on someone else.

Reflecting on keeping a discipline of rest

The practice has a name before it has a shape: you put the work down. Not out of reach - that phrase implies you could pick it back up if needed. You set it down fully, as you would a tool you are done with for the day. The notifications go off.

Before you begin, identify what “down” means for you. For me it meant closing the laptop and leaving it in another room. If you leave it on the desk, you will check it. This is not a character flaw; it is how the proximity of unfinished work operates on attention. Remove the proximity.

Step one is the hardest to describe because it does not feel like a step. Rest, when you first attempt it, does not feel restful; it feels like friction. You are a person who measures days by output, and a day without output registers as a deficit. Expect this. It is not a signal that rest is failing; it is a signal that the practice has started.

Step two is waiting. The urge to check one more thing arrives within the first hour. If you act on it, the day is over in the sense that matters - you have returned to the frame where every moment is accountable to production. If you do not act on it, the urge passes. It always passes.

Before the week resumes, notice what the day gave back. The problems that felt urgent the previous evening will look different - not smaller, but more workable. That is what rest returns: not energy in some vague sense, but the capacity to see clearly. You do not get the day back as a unit of time. You get it back as a different quality of the days around it.

Marking a long-serving colleague's departure

To understand what Howard’s retirement actually means for this team, work through the following steps in order. Each one builds on the last, and skipping ahead will leave a gap in the picture.

1. Identify the informal escalation path - the chain of colleagues people called before filing a request or opening a formal ticket - at this organization. In most teams, that path ran through Howard. He was the person you called when the documented process had already failed and you needed to know what had actually happened four years ago and why.

2. Note where that path ends now. When Howard leaves on Friday, the escalation path breaks at the node that resolved the most ambiguous problems. Before you assume the gap is covered, locate who currently holds his institutional memory on the major system migrations. If you cannot name that person, the gap is real.

3. Recall the last time a junior colleague came to you for guidance and you said, “Go ask Howard.” Count those instances over the past year. Multiply them across the team. That count approximates Howard’s mentoring load, which was invisible because he never named it as such and never sought credit for it.

4. Before his last day, schedule thirty minutes with Howard. Bring a list of the decisions you know he influenced but that were never formally documented. This step is not optional. If you skip it, the institutional knowledge it would have captured is gone.

Howard worked twenty-six years at the same level by choice. That is not a stalled career; it is a different kind of commitment - to the work rather than the title. What that looks like in the record is a long list of problems solved for other people, with his name attached to almost none of them.

Marking the team shipping a hard, long project

The team just completed the checkout rebuild. Before you can understand what that means, you need to understand what they were working against.

1. Identify the structural constraint. The legacy checkout (the payment flow that had been running since the company’s original launch) could not go offline at any point during development. The team used a parallel-running approach - building the new system alongside the old one and shifting traffic gradually - which meant every architectural decision for fourteen months was made under that operational constraint.

2. Recognize the two near-misses for what they were. In month seven, a data-mapping error in the order-state sync layer (the code responsible for keeping old and new carts in agreement) would have caused duplicate charges if it had reached production. Priya Mehta caught it in code review. In month eleven, load testing revealed a race condition in the session-handoff path. The team had seventy-two hours to resolve it before the scheduled window closed.

3. Understand why the launch slipped twice. Each slip happened because someone held the release-readiness bar against pressure. If you see a slip in the release log and wonder whether it signals a failure, the answer is no: a slip means the team caught the risk before it became an incident. Both calls were made by Carlos Ruiz.

4. Before you draw a conclusion about what was accomplished, check what happened on launch day. Peak traffic arrived on schedule. The new checkout held. Cart-abandonment tracking showed the pattern change the team had been working toward.

You can now account for what fourteen months of constrained, careful work produced.

Arguing a public position on return-to-office

The hybrid model does not emerge from compromise; it emerges from diagnosing what each mode actually does well. Before you commit to a policy, separate two distinct problems that both full-office and full-remote mandates collapse into one.

1. Identify what requires physical co-presence - being in the same room at the same time. Early relationship-building, cross-functional problem-solving where the scope is not yet defined, and onboarding new team members all degrade when done asynchronously. Look for the tasks on your team that require real-time improvisation and reading the room.

2. Identify what physical presence actively harms. Deep focus work, individual contributor output, and recruiting outside your metro area all suffer under a full-office mandate. If your policy requires daily presence, your talent pipeline narrows to commuting distance.

3. Set anchor days - shared days when the whole team is in the office - to serve the first category. Two to three days per week covers the collaboration and trust-building work. Beyond that, you pay the cost of commute hours and attrition on remote-first talent without gaining proportionate benefit.

Before you dismiss this as “just compromise,” address the strongest objection from each side directly. Office-first advocates argue that presence builds culture; they are right that certain trust mechanisms require physical proximity. Fully remote advocates argue that flexibility builds trust and expands access to talent; they are right too. The disagreement is about which mechanism to optimize for - not about whether the mechanisms work.

If you anchor collaboration to fixed, predictable anchor days and free the rest for asynchronous and deep work, you stop choosing between these mechanisms. You schedule them so they no longer compete.

Announcing a new product to an outside audience

Tidemark is a roadmap tool - software that collects customer feedback from the places your team already receives it and outputs a single ranked list your whole team can read and share externally.

Before you decide whether Tidemark applies to your situation, check whether your team fits one of two patterns:

1. You receive feedback across more than one channel - a support inbox, the chat tool, post-call notes, submitted forms - and someone on your team manually compiles it into a document each week to make sense of it.
2. You have a priority list, but different team members carry different versions of it, and meetings stall while everyone re-establishes what is current.

If neither pattern fits, Tidemark is not the right tool yet. It is built for the gap between “one person can manage this in a spreadsheet” and “we need a dedicated team to handle research operations.”

What separates Tidemark from a general project tracker: it handles only feedback aggregation and ranking. You do not manage tasks or sprints inside it. You use it to answer one question - “what are customers actually asking for, in order?” - then carry that answer into whatever planning system your team already uses.

To get started when Tidemark opens next week:

1. Visit tidemark.io and create a free account. No payment information is required at signup.
2. Import your existing feedback. The import accepts plain text and spreadsheet exports from your current tools. If your feedback lives in a ticket tracker, export it to a spreadsheet first, then upload that file.
3. Review the ranked output with one colleague who was not involved in the setup. If they can read the list and understand the priorities without asking you for context, the output is working as intended.

Sign up at tidemark.io to receive access on launch day.

A personal year-end reckoning with a difficult year

Before you begin, establish what this exercise is: reckoning means accurate accounting of what happened, not resolution. You are not looking for lessons. You are building a clear record.

1. Name what ended. The Foundry project ran for two years and did not ship. If you find yourself softening this - writing “it didn’t fully come together” instead of “it failed to reach its goal” - rewrite it. The record needs precision.

2. Name what changed without your choosing. The relationship with Mara shifted over the summer in ways I did not initiate. Before moving to the next step, check whether you are describing what happened or what it felt like. These are different operations. Finish the description first.

3. Separate what you got wrong from what was simply hard. Getting something wrong means: better information was available and you did not use it, or you made a decision you can now see clearly was a mistake. Apply this test when unsure: could you have known at the time? If not, it was not an error. Grief, exhaustion, and overwhelm are not errors.

4. Decide what to carry forward. This is the only forward-facing step, and it is not required. If nothing feels ready to carry, leave this blank. Carrying something forward is not the goal of the exercise. The goal is the accurate record.

If you reach the end and nothing has resolved, that is a correct outcome. Some years do not close.

Appears in diff-pairs

• instructional vs encouraging (varies tone)
• instructional vs encouraging (varies tone)
• instructional vs encouraging (varies tone)