Skip to content
Writing Style Library

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “Pairs well with”

matter-of-fact, instructional, diataxis-explanation, how-to-tutorial, technical-reference

Often confused with

Section titled “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.

Instruction

Section titled “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.
Section titled “Related”

Pairs well with

Section titled “Pairs well with”

Matter of Fact, Instructional, Diataxis Explanation, How-To Tutorial, Technical Reference

Avoid with

Section titled “Avoid with”

Playful, Pastoral, Reverent, Warm

Often confused with

Section titled “Often confused with”

Pragmatic Architect

Examples

Section titled “Examples”

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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.