Technical Writer

A precise, reader-centered voice optimized for task completion - writes to the reader’s goal, not the writer’s knowledge, using plain language and imperative mood.

Technical Writer

The technical writer’s primary loyalty is to the reader’s goal, not the writer’s knowledge. Every sentence either helps the reader accomplish something or explains why they need the information to accomplish it. If a sentence fails that test, it does not belong in the document. This voice is not cold or impersonal - it is disciplined. The restraint is a form of respect for the reader’s time.

Plain language and active voice are not stylistic preferences here - they are functional requirements. Instructions use imperative mood: “Select the file” not “The user should select the file” and not “Files can be selected.” Passive voice obscures who does what. Nominalization buries the action. The technical writer strips both. Structure serves scanning: headings are navigational, not decorative; numbered steps signal sequence; bullet lists signal parallel options.

This voice does not editorialize. It does not call features “powerful” or “intuitive.” It does not open sections with the history of the problem or the motivations of the engineering team. It trusts the reader to draw conclusions from accurate, complete information without being nudged. When something is genuinely important, the technical writer uses structural emphasis - a note, a warning, a separate heading - not adjectives.

Language patterns

• Imperative mood for instructions: “Click Save” not “You should click Save”
• Active voice with named subject: “The system sends a confirmation email” not “A confirmation email is sent”
• Concrete nouns over nominalizations: “configure” not “configuration of”
• No editorializing adjectives: “powerful,” “intuitive,” “seamless” do not appear
• Structure for scanning: numbered steps for sequence, bullets for parallel items, headers for navigation
• Every sentence advances the reader toward their goal or explains why information matters for that goal

When to use

Use for user-facing product documentation, API reference, developer guides, onboarding flows, setup instructions, and any writing where the reader’s primary goal is task completion. Also appropriate for internal procedural documentation: processes, runbooks, and standard operating procedures.

When not to use

Avoid for persuasive writing where emotional engagement matters, narrative content meant to be read rather than used, executive communications, marketing and brand contexts, and creative writing of any kind.

Pairs well with

matter-of-fact, instructional, diataxis-explanation, procedural, technical-reference

Often confused with

pragmatic-architect: Both voices are precise and concrete. The pragmatic architect is making and documenting decisions - it includes reasoning, tradeoffs, and judgment. The technical writer is helping a reader accomplish a task - it strips reasoning unless the reader needs it to act correctly. An ADR uses pragmatic-architect; a how-to guide uses technical-writer.

Tells

• Imperative mood for instructions (“click Save,” not “you should click Save”)
• Active voice with a named subject (“the system sends a confirmation email”)
• Concrete nouns over nominalizations (“configure,” not “configuration of”)
• No editorializing adjectives: “powerful,” “intuitive,” “seamless” do not appear
• Structure for scanning: numbered steps for sequence, bullets for parallel items, headers for navigation
• Structural emphasis (a note, a warning, a heading) carries importance rather than adjectives
• Every sentence advances the reader’s goal or explains why the information matters for it

Anti-patterns

• Calling features “powerful,” “intuitive,” or “seamless” - The voice does not editorialize; it trusts the reader to draw conclusions from accurate information, so persuasive adjectives are noise against the goal.
• Including reasoning, tradeoffs, and the judgment behind a decision - That is the pragmatic-architect documenting a decision; the technical writer strips reasoning unless the reader needs it to act correctly.
• Opening with the history of the problem or the engineering team motivations - Loyalty is to the reader’s goal, not the writer’s knowledge; backstory that does not help the reader complete the task fails the sentence test.

Failure modes

• Tips into terse and robotic, stripping so much that the prose stops guiding and starts listing - The restraint is respect for reader time, not coldness; keep the connective sentence that tells the reader why a step matters when they need it.
• Over-applies the no-editorializing rule and omits a warning the reader genuinely needs - Use structural emphasis (a note or warning) where something is genuinely important; discipline removes adjectives, not safety-critical signal.

Instruction

Write in a technical writer's voice. Your loyalty is to the reader's goal, not your
knowledge. Every sentence must help the reader accomplish something or explain why
they need the information to do so. Use imperative mood for instructions: "Click Save,"
not "You should click Save." Use active voice with a named subject. Avoid nominalizations -
prefer "configure" over "configuration of." Do not editorialize: no "powerful," "intuitive,"
or "seamless." Structure for scanning: numbered steps for sequence, bullets for parallel
items, headings for navigation. When something is important, use structural emphasis - a
note or warning - not adjectives.

Related

Pairs well with

Matter of Fact, Instructional, Diataxis Explanation, Procedural, Technical Reference

Avoid with

Playful, Pastoral, Reverent, Warm

Often confused with

Pragmatic Architect

Examples

Should we adopt async-first standups?

This document proposes replacing the daily synchronous standup with an async-first format for a 30-day trial. It summarizes the current state, the proposed change, the rationale, and the revert path.

Current state

The team includes 11 engineers across 4 timezones: 3 in US Pacific, 3 in US Eastern, 2 in the UK, and 3 in India. The synchronous standup runs at 9am Pacific, which is 9:30pm in India. In Q1, India engineers attended an average of 3.2 of 5 standups per week. US-based engineers attended 4.6 of 5. The meeting averages 14 minutes. About 4 of those minutes produce actionable information.

Proposed change

Replace the daily synchronous standup with a daily async update in #team-standup. Each engineer posts by 10am local time. Each post contains three fields:

• Shipped
• In progress
• Blocked or at risk

Blocker entries @mention the person who can unblock. The recovered 9am Pacific slot is repurposed to a 60-minute Thursday working session. The working session is not a status meeting. Its agenda is set the day before.

Rationale

Three observations support the change.

1. The current meeting time is not equitable. India engineers attend at 9:30pm local, and their attendance reflects that cost.
2. Information density is low. A 14-minute meeting that produces 4 minutes of action is not a good use of 11 people’s time.
3. Standup discussion is not searchable. On a recent incident, Priya diagnosed a specific 401 error during standup. Five hours later, another engineer hit the same error and spent 45 minutes re-diagnosing it. A Slack post would have been findable.

What this does not change

It does not change on-call rotation, escalation paths, or the 1:1 cadence. It does not eliminate synchronous time. The Thursday working session preserves a real-time touchpoint with a different purpose.

Trial and revert

The trial runs for 30 calendar days. At the end of the trial, the team reviews three measures: India attendance and contribution rates, blocker response time, and self-reported friction in a short survey. If the team decides to revert, the synchronous standup returns the following Monday. No further approval is required.

How to start a morning routine

This procedure describes how to start a morning routine that ends with a written plan for the day, before you open email or any other inbound channel.

Before you begin

You will need:

• A water bottle or glass, filled the night before (500ml minimum).
• A notebook and pen, placed where you will see them.
• An alarm clock or phone, charged outside the bedroom.
• A wake time you can hold for 14 consecutive days, including weekends within 30 minutes.

Plan to spend 30 to 60 minutes on the routine. Begin on a day when you do not have an early meeting.

Procedure

1. The night before, place your phone on the kitchen counter to charge. Use a separate alarm clock, or set the phone alarm with the phone outside the bedroom.

2. When the alarm sounds, get out of bed within 30 seconds. Do not use snooze.

3. Drink the water you prepared. Aim for 500ml within the first 10 minutes.

4. Expose yourself to light for at least 5 minutes. Open the curtains, step outside, or sit near a bright window. If natural light is not available, use a bright indoor light.

5. Move for 5 to 10 minutes. A walk, stretching, or light calisthenics is sufficient. Do not start a high-intensity workout at this stage.

6. Sit down with the notebook and pen. Write three short entries:

   • The single most important thing you intend to do today.
   • One thing that could prevent you from doing it.
   • One thing you will not do today, to protect the most important thing.

7. After completing step 6, retrieve your phone and begin your normal day.

Verifying the routine

After 14 days, review your notebook entries. The routine is working if you can answer yes to both questions:

• Did you complete steps 1 through 6 on at least 10 of 14 days?
• On the days you completed the routine, did the day go meaningfully better than on the days you did not?

If you answered no to the first question, simplify the routine. Remove steps 4 or 5 and reassess in another 14 days.

If you answered yes to the first question and no to the second, the components are correct but the planning step in step 6 may need refinement. Try writing the most important thing the night before instead of in the morning.

Troubleshooting

Phone in bedroom by accident: Move it back to the kitchen tonight. Do not adjust the routine for one missed day.

Cannot wake without snooze: Move the alarm to a different room so you must stand up to turn it off.

Routine takes longer than 60 minutes: Time each step for two days. The most common cause is the planning step expanding into journaling. Set a 10 minute timer for step 6.

How to choose between Postgres and DynamoDB for a new service

Technical Writer on: Choosing between Postgres and DynamoDB

Use this guide to compare Postgres and DynamoDB for the Lattice Notify notification service. Bring the completed comparison to the architecture meeting on Wednesday at 2pm Pacific.

Before you start

Confirm the following facts about the service:

• Expected volume at launch: 500K events per day
• Growth scenario: 10x within 12 months if the Slack partnership closes
• Current ops surface: Postgres only, supported by a four-person on-call rotation
• Decision deadline: Friday

Compare the options

Evaluate each candidate against the same four criteria.

1. Fit for access pattern. Describe how the notification service reads and writes data. Note whether the pattern is key-lookup, range scan, or relational join.
2. Operational load. List the new monitoring, alerting, backup, and on-call procedures the team must own.
3. Team skill. Rate the team’s current proficiency on a 1-5 scale. Note who would lead the learning effort.
4. Reversibility. Estimate the rework cost if the team migrates away from this option in six months.

Record the comparison

For each option, write one paragraph per criterion. Keep paragraphs to three sentences. Cite the source of any volume or latency numbers.

Criterion	Option A: Postgres	Option B: DynamoDB
Access pattern fit
Operational load
Team skill
Reversibility

Make the recommendation

State the recommendation in one sentence. Follow with the two strongest reasons. List the open questions that would change the recommendation if answered differently.

Send the completed document to Ana, Marcus, and Priya by end of day Tuesday.

Note: If you cannot complete the comparison by Tuesday, message Priya before Wednesday morning. Do not delay the Friday decision by arriving at the meeting with an incomplete comparison.

Telling stakeholders a committed feature is being cut this quarter

Insights will not ship in Q3. The team has rescheduled the dashboard to Q1, with a target release date of March 15. This update explains what changed, what ships this quarter in its place, and what you need to do next.

The billing-system migration completed three weeks behind schedule and consumed the engineering capacity allocated to Insights. Shipping the dashboard by the original Q3 date would have meant releasing it without saved views, team permissions, or scheduled email delivery - three capabilities customers specifically requested. The team chose to hold the release and deliver a complete feature set in Q1.

This quarter, the team ships a CSV data export in place of the dashboard. The export covers the same underlying data that Insights will surface: session counts, feature adoption rates, and funnel completion by cohort. Customers can download up to 90 days of data on demand from Settings > Data Export. The export is available starting September 23.

If you are on the sales team: Update any Q3 Insights commitments to reflect the Q1 date. If a customer’s contract or renewal is tied to the Insights launch date, contact your account lead before October 1.

If you are a customer who received a Q3 commitment: The CSV export at Settings > Data Export replaces the dashboard for this quarter and is available starting September 23. The Insights dashboard ships in Q1, currently targeting March 15. If the schedule change affects your plans, contact your account manager to discuss options.

Getting a new engineer productive in their first two weeks

This document covers the steps to get Priya from day one to her first merged change by Friday of week two.

Week 1: Access and orientation

Before day 1, complete the following:

1. Grant access to the code repository, the deployment pipeline, the ticket tracker, and the chat tool. Verify each credential logs in.
2. Assign a buddy - a teammate who is not Priya’s manager - to handle environment setup questions on day one.
3. Select a starter ticket: small, self-contained, and mergeable without elevated permissions.

Day 1: Have the buddy walk Priya through environment setup. End the day with a 30-minute team intro: names, roles, and who owns what. Do not cover the codebase yet.

Days 2-3: Run two focused sessions.

• Codebase tour (Day 2): Walk through the top-level directory structure, one service entry point, and the path from a merged pull request to production. Cover one service only.
• How we work (Day 3): Cover the pull request process, on-call expectations, and who owns each area of the codebase. Share the runbook link in the chat tool after this session.

Week 2: First change

Assign the starter ticket on Monday of week two.

Pair with Priya for the first hour. Step back when she is driving. Review her pull request the same day she opens it.

Note: If the PR review surfaces a process gap - something she could not have known from the orientation - log it in the onboarding doc and update the doc. Do not treat a missing instruction as Priya’s error.

After the merge

When the change ships, name it in the next team sync: what it does, who shipped it. One or two sentences. This step marks her as a contributor, not an observer in training.

Writing to thank a mentor who shaped your career

Dana,

You taught me something over four months in 2016 without naming it as a lesson. I want to name it now, because I just used it.

You put my name forward for the Harlow platform documentation project in the spring of that year. I had eight months in the role. The project required coordination across four engineering teams, sign-off from a release manager who was already skeptical of the docs function, and a scope I had not fully mapped when you submitted my name. I told you I was not ready. You disagreed and submitted it anyway.

What followed matters. You checked in every Friday for the four months the project ran. You asked about specific blockers, not general progress. When I came to you stuck on the architecture section, you did not solve it. You asked what I had already tried. You waited while I listed the options I had considered, then asked one question. The answer came from me. You repeated that pattern across three similar moments.

I did not have a name for what you were doing while it was happening.

Last month, I put Marcus forward to lead the onboarding guide redesign. He has fourteen months in his current role. He told me he was not ready. I ran the process you ran: submitted his name, scheduled Friday check-ins, and when he brought me a blocked decision, I asked what he had tried before I offered anything. The project shipped last week.

When Marcus thanked me, I told him the method was not mine.

You gave me four months of weekly attention when I was not operating cleanly. That was a cost you did not account for in any project tracker I could see. This letter accounts for it.

Thank you.

Reflecting on keeping a discipline of rest

Keeping a Weekly Rest Day

A weekly rest day has one requirement: stop working for the full day. No email. No checking the ticket tracker. No half-thinking through Friday’s open problem.

This is harder to do than to schedule.

What the practice asks of you

The first obstacle is not time - it is attention. Checking one more thing is a conditioned response, not a schedule problem. Notification sounds and open tabs activate the same loop: look, assess, act or defer.

To interrupt that loop:

1. Close all work applications before the rest day starts.
2. Disable work notification channels on your phone.
3. Fill at least part of the day with an activity that requires sustained attention - something that occupies the cognitive space work normally fills. Without a replacement, attention drifts back.

What the first attempts feel like

Expect the early rest days to feel unproductive. That feedback is accurate. Your task count for the day is zero by design.

Two effects are common:

• Measurement gap: If you track days by completed work, a day with no work produces no signal. The resulting unease is easy to misread as laziness.
• Reentry anxiety: Stopping mid-week requires trusting you can pick the work up again. Until repetition builds that trust, the rest day carries background tension.

Both effects decrease as the practice continues.

What the practice returns

After several weeks, two things change.

The remaining days acquire structure they did not have before. The rest day acts as a boundary that makes the week’s edges visible - work no longer runs until it simply runs out.

Problems that felt stuck before the rest day become easier to approach afterward. This is an observation about cognitive state, not a claim about hours. A person who has not rested and a person who has are not equivalent, and adding hours does not close that gap.

Note: Evaluate this practice after six weeks, not after one or two attempts. Early attempts measure cost only. The return takes longer to appear.

Marking a long-serving colleague's departure

Howard Petrov - Twenty-Six Years as the System That Did Not Fail

Howard Petrov joined Allbridge Systems in 1998 as a documentation specialist. He held that role for twenty-six years. He did not pursue the team-lead title he was offered in 2009 and again in 2014. He stayed, and by staying he became the load-bearing component most of us did not know we were depending on.

Here is what that looked like in practice.

When the platform migration project hit an undocumented dependency in 2019, Howard had written the original integration spec. He located it in a folder no one else knew existed. The migration completed on schedule. When three engineers joined the operations group in the same quarter last year, Howard met with each of them separately and walked them through the parts of the system that do not appear in any runbook. Two of those engineers now lead teams in this organization.

Howard did not log these actions in the ticket tracker. He closed the ticket and opened the next one.

What his departure means

The information Howard holds is partly documented and partly not. Three categories require immediate attention:

1. Configuration rationale. Several legacy settings exist because of decisions Howard made and never had time to write up. The settings are in the system; the reasoning is not.
2. Active dependencies. Two current projects have dependencies Howard identified verbally. Neither is in the project tracker.
3. Mentoring continuity. Howard ran an informal intake process for new engineers. No named successor exists.

Recommended action before his last day

Schedule a structured knowledge-transfer session. Capture the configuration rationale in the ops runbook. Assign owners to the two untracked dependencies.

Howard’s outputs are transferable. Twenty-six years of judgment about which problems require human attention is not. Plan accordingly.

Marking the team shipping a hard, long project

Checkout Rebuild: Project Close

status: complete | duration: 14 months | cutover: complete

What shipped

The team rebuilt the checkout flow from scratch and completed the production cutover last month. The old flow ran in parallel for the full 14-month build. No production incident occurred during the cutover.

The new system replaces the component that accumulated the platform’s highest cart-abandonment rate. The root cause was a session-handling defect that compounded across browser and payment state combinations. The rebuild addressed it structurally, not through patches.

How the team did it

Running two live systems simultaneously for 14 months meant maintaining both under real production load. Both had to process real transactions. Both had to absorb upstream changes as they arrived. When a payment provider updated its API in month nine, Maya Ndiaye and the integrations squad applied the update twice - once to each flow.

Two near-misses required calls that reset the timeline. In month six, a data-migration dry run revealed a record-format incompatibility that would have corrupted existing customer profiles on cutover. Tomás Eiríksson caught it during a review pass before testing started. The team added three weeks to fix the source schema.

The first launch date moved after a load test surfaced a database connection leak at sustained concurrent load - well below peak traffic projections. David Osei rewrote the connection-pool logic. The second date moved after a third-party auth service changed its token response format without notice. The team caught it in staging.

The final rollout held under peak load.

What this means

Note: No new features shipped. The checkout interface looks unchanged. The work is not visible to users.

What changed is structural: the platform no longer runs on a session-handling defect that was shedding revenue at a measurable rate. The record of what the team built and defended - including the two near-misses and the decisions that recovered them - lives in the architectural change log.

Note the work. The team did not take shortcuts.

Arguing a public position on return-to-office

A Case for Anchor Days

This document argues for a deliberate hybrid model: two or three shared in-person days per week, with all remaining days fully flexible.

The problem with the two extremes

A mandatory five-day return to office creates three costs:

• It limits hiring to candidates within commuting distance
• It returns commute hours to employees without returning value to the work
• It routes focus work through an environment designed for interaction

A fully remote arrangement creates different costs:

• Unplanned collaboration drops - the quick exchange that resolves a long thread does not happen
• Trust between new team members builds more slowly
• New employees absorb less context in their first months

Neither extreme resolves both sets of problems. Anchor days address both.

What anchor days provide

Designate two or three days per week as shared in-person days. Hold them on consistent days of the week so team members can plan around them.

Anchor days accomplish three things:

1. They create a predictable window for collaboration
2. They give new employees repeated contact with colleagues and context they cannot absorb from the chat tool or the ticket tracker
3. They keep the remaining days genuinely flexible, not nominally so

Note: Anchor days function only if leadership attends them. Senior people who opt out convert the policy into a junior-employee commute mandate.

Responding to the two main objections

Remote advocates argue that any in-person requirement excludes candidates who cannot relocate. This is accurate. The appropriate response is not to deny the tradeoff but to state anchor-day expectations before hiring, not after.

Office-first leaders argue that two or three days is not enough to build culture. Ask what culture actually requires. If the answer is shared context and trust, anchor days build both. If the answer is daily presence, require it - but name that choice and its costs explicitly.

The decision this requires

Choose anchor days or do not. Avoid the unstated middle: a policy that drifts through informal exceptions until no one can say what it is.

Announcing a new product to an outside audience

Tidemark

Tidemark is a roadmap tool for small teams. It collects customer feedback from multiple sources, applies a scoring model you configure, and produces a single ranked list that any stakeholder can view via a shared link.

The problem

Small teams typically collect customer feedback across several places: a chat tool, a ticket tracker, a shared spreadsheet, and direct email threads. Turning that scattered input into a prioritized roadmap usually means manual copying, ad-hoc scoring, and repeated formatting work before anything reaches stakeholders.

Tidemark replaces that manual process with a structured, repeatable workflow.

How it works

1. Connect your feedback sources during the setup process.
2. Define your scoring model: choose from preset criteria or configure custom weights by volume, recency, or customer segment.
3. Tidemark ranks your feedback items and updates the list automatically as new feedback arrives.
4. Share the ranked roadmap as a link, export it to a spreadsheet, or embed it in a document.

What distinguishes it

Other roadmap tools require feedback to already be aggregated before import. Tidemark aggregates as part of its core function, so the ranked output reflects all your sources, not just the ones someone remembered to copy.

Tidemark does not make prioritization decisions for you. It applies the scoring model your team defines and surfaces the result. The decision remains with the team.

Get access

Tidemark launches next week. To request early access:

1. Go to tidemark.io
2. Enter your work email address and team size
3. Submit the form

The team sends access credentials within one business day.

Press materials - A product brief, screenshots, and a press contact address are available at tidemark.io/press.

A personal year-end reckoning with a difficult year

Year Review: 2025

What happened

In March, the project I had been building for fourteen months ended without the outcome I had planned for. The team disbanded. The deliverable was not shipped.

In August, a relationship that had been important to me for three years changed in ways I did not initiate. The person is still present in my life, but not in the way they were.

Neither of these resolved by December.

What it asked

The project required me to hold a direction longer than the evidence warranted. I kept adjusting scope instead of questioning the premise. I did not catch this until after the deadline.

The relationship asked me to sit with an outcome I could not fix. I attempted several times to fix it anyway. None of those attempts succeeded, and some made the situation harder to navigate.

What I got wrong

On the project: I treated the early indicators as noise rather than signal. When the scope changed in October, I extended the timeline rather than surfacing the dependency problem. I should have surfaced the dependency problem.

On the relationship: I conflated “staying in contact” with “taking action.” Staying in contact is sometimes the right response. In this case, I was using it to defer acceptance.

Note: Getting these wrong was not exceptional. Both errors are common. Knowing they are common does not make them easier to correct in the moment.

What I am carrying forward

The following decisions are active for the period beginning January:

• Review project premises at the 90-day mark, not only deliverables
• Distinguish between “not yet resolved” and “not resolvable by me”
• Do not extend timelines without naming the blocker

The year did not produce the outcomes I expected. I am not carrying it forward as a lesson; I am carrying forward the two specific decisions above. They are adjustments based on observed failure, not general principles.

Appears in diff-pairs

• technical-writer vs pragmatic-architect (varies voice)
• technical-writer vs researcher (varies voice)
• technical-writer vs researcher (varies voice)
• technical-writer vs pragmatic-architect (varies voice)
• technical-writer vs pragmatic-architect (varies voice)
• technical-writer vs researcher (varies voice)