Common Mistakes in Technical Writing

Technical writing fails in predictable ways. The same mistakes appear across design documents, API docs, runbooks, and blog posts, written by junior developers and staff engineers alike. These are not matters of style or taste — they are patterns that measurably reduce how well a document communicates. Passive voice that hides who does what. Inconsistent terminology that confuses. Undefined acronyms that exclude. Burying the lead so the reader never finds the point. This chapter catalogs the most common mistakes and shows how to fix each one.

Passive Voice Overuse

Passive voice is not grammatically wrong. But in technical writing, it consistently causes problems because it hides the actor — and in technical contexts, knowing who or what performs an action is critical.

Passive (who does this?):
  "The configuration file is loaded at startup."
  "Errors should be logged before retrying."
  "The database is backed up nightly."

Active (clear actor):
  "The application loads the configuration file at startup."
  "The retry handler logs errors before retrying."
  "A cron job backs up the database nightly."

In every passive example, the reader cannot answer a basic question: what does this? That matters because when something breaks at 3am, the on-call engineer needs to know which component, service, or process is responsible.

When Passive Voice Is Acceptable

Passive voice is fine when the actor genuinely does not matter or is unknown:

Acceptable passive:
  "The TCP connection is terminated after 30 seconds of inactivity."
  [The reader does not need to know whether the kernel, the load balancer,
   or the application does this — the behavior is what matters.]

  "This field was deprecated in version 3.2."
  [Who deprecated it is irrelevant. When it happened matters.]

The test: if switching to active voice would require naming an actor that the reader does not care about, passive is fine. If the actor matters, use active voice.

Inconsistent Terminology

Using multiple terms for the same concept is one of the most damaging mistakes in technical writing. It forces the reader to figure out whether different words mean different things or the same thing.

Inconsistent (are these the same?):
  Paragraph 1: "The server processes incoming requests."
  Paragraph 2: "The node handles traffic from clients."
  Paragraph 3: "The instance responds to API calls."
  Paragraph 4: "The host manages the workload."

  [Server, node, instance, host — are these four different things
   or one thing with four names?]

Consistent:
  Paragraph 1: "The server processes incoming requests."
  Paragraph 2: "The server handles traffic from clients."
  Paragraph 3: "The server responds to API calls."
  Paragraph 4: "The server manages the workload."

In literary writing, repetition is considered poor style and writers use synonyms for variety. In technical writing, that instinct is destructive. Use the same word for the same concept every single time. The reader's ability to follow your argument depends on terminological consistency.

Inconsistency creeps in through multiple authors, writing over multiple days, and the instinct to rotate synonyms for "better writing." Fix: before publishing, search for all terms that refer to the same concept and standardize to one.

Undefined Acronyms

Every acronym is a barrier. The reader either knows it or does not. If they do not, they must stop reading and search for the definition — or worse, they guess wrong and misunderstand everything that follows.

Hostile to the reader:
  "The SLO requires P99 latency under 50ms for all RPC endpoints.
   The ORM adds ~10ms, so we need the DB queries to complete in
   under 40ms, which means PgBouncer's pool size must match the
   max K8s pod count times the per-pod thread limit."

Accessible:
  "Our service-level objective (SLO) requires that 99th percentile
   (P99) latency stays under 50ms for all remote procedure call
   (RPC) endpoints. The object-relational mapper (ORM) adds roughly
   10ms of overhead, so database queries must complete in under 40ms."

The Rule

Define every acronym on first use. After defining it once, use the acronym freely. No exceptions for "common" acronyms — what counts as common depends entirely on the reader.

Format: "Full Name (ACRONYM)"

  "We use Amazon Elastic Kubernetes Service (EKS) for orchestration."
  [All subsequent uses: "EKS"]

  "The continuous integration (CI) pipeline runs on every push."
  [All subsequent uses: "CI"]

For documents longer than a few pages, consider a glossary at the top or bottom if acronym density is high.

Burying the Lead

Burying the lead means putting the most important information somewhere other than the beginning. In journalism, this is considered the cardinal sin. In technical writing, it is equally damaging.

Lead buried:
  "Over the past quarter, the infrastructure team has been
   evaluating various options for improving our deployment
   pipeline. We considered several approaches including
   blue-green deployments, canary releases, and rolling
   updates. After extensive testing and discussion with
   stakeholders across multiple teams, taking into account
   factors such as cost, complexity, and reliability...

   ...we recommend switching to Argo Rollouts for canary
   deployments."

  [The recommendation — the only thing the reader needs — is buried
   after a paragraph of process description.]

Lead first:
  "We recommend switching to Argo Rollouts for canary deployments.
   It reduces deployment risk at a cost of ~$200/month and moderate
   configuration complexity. Here is what we evaluated and why we
   chose this approach."

Put the conclusion first. Then the evidence. The reader should never have to read your entire document to find out what you are recommending.

The BLUF Principle

Bottom Line Up Front (BLUF): state your conclusion, recommendation, or finding in the first paragraph. The rest of the document supports that statement.

BLUF applied to common document types:

  Design doc:    "We should use PostgreSQL, not MongoDB, for the
                  new inventory service. Here's why."

  Incident report: "The 47-minute outage on March 3 was caused by
                    a misconfigured health check threshold."

  Status update:   "The project is two weeks behind schedule due to
                    an underestimated data migration."

Assuming Context

The reader does not have your context. They have not been in your meetings. They do not know what you tried before. They may not even work on your team. Writing that assumes shared context excludes everyone who does not have it.

Assumes context:
  "As we discussed, the current approach won't scale. We need
   to switch to the new architecture before the launch."

  [What current approach? What about it won't scale? What new
   architecture? What launch?]

Provides context:
  "The current single-threaded request handler can process about
   500 requests per second. The product launch in Q3 requires
   handling 5,000 RPS. We need to switch to the async handler
   architecture described in RFC-247 before the launch date
   of September 15."

The Test

Imagine someone joins your team next month and reads this document. Would they understand it without asking you questions? If not, the document is missing context.

Context assumptions to check:

  - References to meetings, conversations, or decisions without explanation
  - "The issue" or "the problem" without stating what it is
  - Version numbers or dates without explaining what changed
  - "We decided to..." without explaining the options or criteria
  - Links to internal documents without summarizing the relevant content

No Examples

Abstract explanations without examples are the hallmark of writing that informs but does not teach. The reader understands the concept in theory but cannot apply it in practice.

Abstract only:
  "Rate limiting can be implemented using a token bucket algorithm.
   Tokens are added to a bucket at a fixed rate, and each request
   consumes one token. When the bucket is empty, requests are
   rejected."

With example:
  "Rate limiting can be implemented using a token bucket algorithm.
   For example, to allow 100 requests per minute per user:

   bucket_size: 100
   refill_rate: 100 tokens per 60 seconds (~1.67 tokens/second)

   A user making 50 requests in the first second consumes 50 tokens.
   They have 50 remaining. If they then make 60 requests in the next
   second, only 51 succeed (50 remaining + ~1.67 refilled). The
   remaining 9 are rejected with HTTP 429."

The example turns an abstract algorithm into concrete behavior the reader can verify against their own requirements.

The Rule of Examples

Every concept that the reader needs to apply should have at least one example. If you are explaining a configuration option, show a configuration. If you are explaining a pattern, show code. If you are explaining a decision framework, walk through a real decision.

Walls of Text

A long paragraph with no structural breaks is a signal that says "this will be hard to extract information from." Readers skim technical documents. If they cannot find the section they need, they leave.

Structural tools you should be using:

  - Headings every 3-5 paragraphs
  - Code blocks for anything that is code, config, or output
  - Bullet lists for sets of items
  - Numbered lists for sequences
  - Tables for comparisons
  - Bold for key terms or the first sentence of important paragraphs
  - Short paragraphs (3-5 sentences maximum)

Breaking Up Walls

When you see a paragraph longer than 5 sentences, ask: "Is this one idea or several?" If it is several, split it. If it is one idea, look for parts that can become a list or a code block.

Before (wall of text):
  "The configuration file supports three modes: development, staging,
   and production. In development mode, logging is set to DEBUG, hot
   reloading is enabled, and the database uses a local SQLite file.
   In staging mode, logging is set to INFO, hot reloading is disabled,
   and the database connects to a shared PostgreSQL instance. In
   production mode, logging is set to WARN, hot reloading is disabled,
   and the database uses a connection pool with read replicas."

After (structured):
  "The configuration file supports three modes:

   Development:
     - Logging: DEBUG
     - Hot reload: enabled
     - Database: local SQLite

   Staging:
     - Logging: INFO
     - Hot reload: disabled
     - Database: shared PostgreSQL

   Production:
     - Logging: WARN
     - Hot reload: disabled
     - Database: connection pool with read replicas"

Same information. The structured version takes less time to read, is easier to reference, and is harder to misread.

Writing to Impress Instead of Inform

Some technical writers use complex vocabulary, dense sentence structures, and abstract language because they think it makes them sound more authoritative. The opposite is true. The most respected technical writers use simple language.

Writing to impress:
  "The implementation leverages a sophisticated multi-layered
   caching paradigm that facilitates optimal resource utilization
   through a synergistic combination of in-memory and distributed
   cache topologies."

Writing to inform:
  "We use two cache layers: an in-memory cache (local to each server)
   for hot data, and a Redis cluster for shared data. The in-memory
   cache handles 80% of reads. Cache misses fall through to Redis."

The second version communicates more information in fewer words. The reader walks away knowing the architecture, the technology choices, and the performance characteristics. The first version communicates nothing specific.

The Test

After writing a sentence, ask: "Would I say this to a coworker at a whiteboard?" If the answer is no — if you would say something simpler and more direct in conversation — rewrite the sentence to match how you would explain it in person.

Common Pitfalls

• Fixing grammar but not communication. A grammatically perfect document that buries the lead and assumes context is still a bad document. Prioritize communication over correctness.
• Over-correcting on passive voice. Not all passive voice is bad. Fix it when the actor matters and is hidden. Leave it when the actor is irrelevant.
• Defining acronyms only in a glossary. Define them inline on first use. Most readers will not scroll to a glossary.
• Adding examples that are too simple. An example with one item in a list or a trivial input does not demonstrate real usage. Use realistic examples.
• Structuring for the writer instead of the reader. Chronological order (what we did first, second, third) is natural for the writer but often wrong for the reader. Structure by importance instead.
• Treating all readers as the same. A runbook reader at 3am needs different things than a design doc reader during planning. Know your audience.

Key Takeaways

• Use active voice when the actor matters. "The cron job backs up the database" tells the on-call engineer what to check. "The database is backed up" does not.
• Use one term per concept, consistently, throughout the document. Synonym rotation creates confusion.
• Define every acronym on first use. What counts as "obvious" depends on who is reading.
• Put the most important information first. Conclusions, recommendations, and findings belong in the opening paragraph.
• Provide context a newcomer would need. If someone joining your team next month cannot understand the document, it is missing context.
• Include examples for every concept the reader needs to apply.
• Break up walls of text with headings, lists, code blocks, and short paragraphs.
• Write to inform, not to impress. Simple language communicates better than complex language.