Helping you learn practical, straightforward methods to boost your soft skills and enhance your career as a software engineer.

---

Weekly Newsletter

November 25th, 2025

You Are Writing Documentation Wrong

Most technical docs fail for a simple reason: they are written for the author, not the reader.

The person who did the work already knows the system, the history, and the weird edge cases. So they write from that viewpoint. They skip context, assume shared language, and mix design decisions, how-to steps, and loose notes into one long page. The result is familiar. You open the doc, skim for a minute, and then ask in Slack anyway.

The cost is not small. One analysis of Stack Overflow’s 2022 developer survey notes that 62% of developers spend more than 30 minutes a day searching for information about poorly documented issues, and a quarter spend over an hour.

​Atlassian’s 2025 State of DevEx report found that, even with AI tools saving time, 90% of developers still lose 6 or more hours a week to organizational friction, such as hunting for information, and that teams with good self-serve information are over 4 times more productive. Poor documentation and hard-to-find context continue to be top productivity drains.

Good docs do something different. They answer three questions:

• What is this
• Why does it matter
• How do I use it

This week, we will walk through a simple way to improve your technical writing. You will learn how to tune your docs to the right audience, choose the right kind of document, and use a short checklist to decide what to include and what to skip. At the end, you will get a 20-minute “doc tune-up” you can run on something you have already written.

Start With the Reader, Not the System

Before you write a single sentence, decide who the document is for and what you expect them to do with it.

Most docs start from the system. Architecture. Components. Data flows. That is useful, but it is not the starting point. The starting point is the reader’s job to be done.

​Google’s technical writing material puts it in an equation. Good documentation = the knowledge and skills your audience needs to do a task, minus what they already have.

That only works if you are explicit about both sides.I like to write a small “audience card” at the top of the doc before anything else:

Who is this for?​
“Backend engineers on the Orders team” or “New support engineers in onboarding.”

What are they trying to do?​
“Understand the tradeoffs behind the new billing service” or “Run this incident playbook without waking someone up.”

What do they probably know already?​
“Comfortable with our stack and AWS, new to our billing rules.”

What happens if they get it wrong?​
“Customers can get double-charged,” or “We miss our response-time SLA.”

This takes two minutes and shapes everything that follows. It tells you how much context to include, how deep the How should go, and which doc type fits.

If the reader needs to make a decision, you are probably writing a design or explainer. That doc should lean hard on the Why and less on the step-by-step How.

If the reader needs to execute a task, you are probably writing a runbook or how-to. That doc should lean hard on the How and keep the Why short and to the point.

Once you have the audience card and the job to be done, the What/Why/How checklist becomes a filter rather than a template. You stop asking “What else can I add?” and start asking “What does this specific reader actually need?”

Use What/Why/How as Your Backbone

Once you know who you are writing for and what they need to do, you can shape the document around three questions:

• What is this
• Why does it matter
• How do I use it

This sounds simple, but most docs skip at least one of these. That is usually where readers fall off.

What: Name the thing in plain language

Start with one or two short sentences that answer “What is this?”

You are trying to give the reader a handle they can grab.

Good “What” sections:

• Use simple, specific language.
• Say what this is and what it is not.
• Avoid buzzwords and internal code names unless you define them.

Example:

“This document describes the new billing service that replaces our legacy invoice batch job. It covers how the service works today and the constraints it must meet.”

That is enough for the reader to know where they are and whether they should keep reading.

Why: Explain the reason this exists

Next, explain why this matters.

This is not a full business case. It is a short summary of the problem and the stakes.

Useful “Why” sections usually cover:

• The problem or risk you are solving
• The outcome you want
• The key constraints or tradeoffs

Example:

“The current batch job fails silently and can double charge customers. The new service must support real-time invoicing, clear error handling, and accurate audit logs so Finance can reconcile payments.”

Now your reader understands the context. They know what success looks like and why the details that follow are important.

How: Match the depth to the reader’s job

Only after What and Why do you get to How.

“How” is where most engineers start. It is also where most readers get overwhelmed.

The trick is to match the depth of the How to the reader’s job.

• If they need to make a decision, focus on high-level architecture, tradeoffs, and options.
• If they need to run a task, focus on concrete steps, commands, and examples.
• If they need to look something up, focus on precise behavior and reference tables.

You do not have to put every detail in one place. Often the best move is:

• High-level How in the main doc
• Links to code, ADRs, or reference docs for deeper details

This aligns with what good technical writing courses recommend: clear structure, focused paragraphs, and a deliberate use of examples.

When you treat What / Why / How as the backbone, you give your reader a predictable structure. They can skim to the parts they care about and still keep the full picture in their head.

Pick the Right Doc Type for the Job

Once you know your reader and have a What / Why / How backbone, the next mistake to avoid is trying to make one document do every job.

Design notes, onboarding guides, incident runbooks, and API references are different tools. When you mix them together, nobody can find what they need.

The Diátaxis framework is a helpful mental model here. It splits documentation into four kinds: tutorials, how-to guides, reference, and explanation, each serving a different user need.

The Software Engineering at Google book makes a similar point with engineering language: design docs, how-to docs, project pages, and code comments are all “documentation,” but each should have a singular purpose, just like an API.

I usually sort working docs into four buckets.

1. Design and decision docs

Goal: Help people understand and evaluate a change.

• Reader job: “Should we do this? What are we trading off?”
• Emphasis: Heavy on Why and high-level What, light on step-by-step How
• Good signs: Clear problem statement, options considered, chosen approach, and explicit tradeoffs

If your main reader is a tech lead, architect, or product partner, you are probably here. For a deeper example of this style, the “Design Docs at Google” write-up is a good reference.

2. How-to guides and runbooks

Goal: Help someone execute a task with low stress.

• Reader job: “How do I do this correctly, especially under pressure?”
• Emphasis: Heavy on concrete How, short What,and Why up front
• Good signs: Ordered steps, clear pre-conditions, expected outcomes, and “what to do if” sections

If you imagine someone using your doc at two in the morning during an incident, you will write it differently.

3. Reference docs

Goal: Let people look things up quickly.

• Reader job: “What does this field mean? What does this endpoint return?”
• Emphasis: Precise What and targeted How in the form of examples
• Good signs: Tables, parameter lists, short example calls, and consistent structure

Reference is where details belong. It should answer specific questions without storytelling.

4. Explainers and onboarding guides

Goal: Build mental models.

• Reader job: “How does this system fit together? What do I need to know to work in this area?”
• Emphasis: Balanced What and Why, selective How at a high level
• Good signs: Diagrams, narratives about flows, and links out to designs, runbooks, and reference

These are for new teammates or cross-team partners who need to get oriented fast.

A simple rule of thumb:

• One main reader
• One main job to be done
• One primary doc type

You can always link to other doc types. You do not need to cram everything into one page.

Fight the Curse of Knowledge

Once you have the right doc type, the main enemy is what you already know.

When you are close to a system, it is hard to remember what it feels like to see it for the first time. That is the curse of knowledge. You skip steps, use internal jargon, and assume the reader can fill in the gaps.

You will not fix this by trying harder. You fix it with a few simple habits.

1. Assume “smart, but new to your world.”

Do not write for “a beginner.” Do not write for “an expert.”

Write for someone who is smart, but new to this specific thing.

That mindset pushes you to:

• Define acronyms the first time you use them.
• Add one short paragraph of system context before diving into details.
• Explain local terms like project code names or internal tools.

You are not talking down to them. You are giving them on-ramps.

2. Add scaffolding instead of more words

Most people respond to confusion by adding more detail. That usually makes the doc worse.

Instead, add scaffolding:

• Headings that tell the reader what they will get
• Short summaries at the top of long sections
• Diagrams for flows that are hard to track in text
• “Prerequisites” and “Out of scope” lists so they know what to expect.

This is the same pattern I talked about in The Hidden Communication Skill That Will 10x Your Impact. You are not trying to sound smart. You are trying to make it easier for others to follow the thread.

3. Use small, concrete examples

Abstract descriptions are easy to write and hard to understand.

Examples do more work with fewer words. Add:

• One sample API call with inputs and outputs
• One real incident scenario in a runbook
• One concrete use case in a design doc

Keep the example small and realistic. Enough to show the reader how the pieces fit together.

4. Run one real-world test

If the doc actually matters, test it with a real reader.

Ask someone from the target audience to:

• Use the doc to complete a task.
• Mark every spot where they had to guess or ask a question.

You will see exactly where the curse of knowledge hits you. Fix those spots first. Often, you will find that a one-line clarification or a short diagram does more than an extra page of explanation.

---

Good technical documentation is not about writing more. It is about sharing the right information for the person in front of you.

When you start with the reader, build around What, Why, and How, and choose a single doc type, you remove most of the friction. The curse of knowledge does not disappear, but simple habits and small tests keep it from leaking into every page you write.

If you want a concrete next step, grab one doc you are responsible for and run a quick tune-up this week. See what changes for the people who use it.

And if you are stuck on a specific document or unsure how much context to include, hit reply and send it to me. I am happy to take a look.

---

Follow MoreThanCoders