Writing for Developers vs Non-Technical Users

Last week I documented douglasebhoman.com, my personal portfolio site.

I built it. Every line of HTML, every CSS variable, every deployment pipeline. I made every architectural decision, named every class, wrote every commit message. There is no version of this site I don't understand.

And yet, writing developer documentation for it was one of the hardest writing tasks I've done.

Not because the system was complex. Because I knew it too well.

Every assumption I'd made during the build, assumptions so familiar they had become invisible, suddenly needed to be surfaced, named, and explained for someone who wasn't me. The curse of knowledge doesn't spare you just because the system is your own. It hits harder.

That experience gave me something I couldn't have gotten from reading about developer documentation: a felt understanding of why writing for developers and writing for non-technical readers are not just different tones. They are different jobs entirely.

The tour guide and the expert escort

Writing a blog series is like taking your audience on a tour. There's a specific destination, but the journey is the point. You show the reader every detail along the way, not because they need all of it, but because context is what makes the content worth reading. The narrative earns the information.

Writing developer documentation is different. You're not a tour guide. You're an expert escort who takes the reader directly to the destination, stripping out everything that doesn't serve the task. No history. No exploration. No detours through your own thinking.

Precision is the value. Every word that isn't load-bearing is a word that shouldn't be there.

What made documenting my own site so disorienting was that I had to become the escort for a destination I'd built myself. I had to pretend I didn't know the shortcuts. I had to write the long way for a reader who needed the long way, even though I'd never taken it.

That's the job. And it's harder than it sounds.

The developer wants results. The non-technical reader wants understanding.

When their needs align, writing for both audiences is straightforward. When they diverge, they diverge completely.

Consider the same piece of information written for two different readers.

For a developer:

GET /users/{id}
Returns a single user object.
Parameters: id (string, required) — the unique user identifier.
Response: 200 OK { "id": "abc123", "name": "Douglas Ebhoman" }

For a non-technical reader: "Think of the user ID as a library card number. When you ask the system for a specific user, you hand over their card number and the system retrieves everything it knows about them."

Same information. One gives the developer exactly what they need to act. The other gives the non-technical reader exactly what they need to understand. Neither version works for the wrong audience.

Part of writing for developers is also meeting them in their environment. A non-technical user reads a Help Centre article or a PDF. A developer often reads a README.md in a Git repository or documentation embedded directly in their IDE. The format is part of the message.

Where technical writers most often get this wrong

There are two failure modes and most writers fall into one of them. Both come from the same root problem.

The first is not trusting the developer. Over-explaining code samples. Defining syntax that any working engineer already knows. Adding context the developer didn't ask for and doesn't need. The result is documentation that wastes their time and signals clearly that the writer doesn't understand who they're writing for.

The second is underestimating the non-technical reader. Assuming they know what an API is, what a parameter does, what an acronym means. The result is documentation that informs no one, too thin for a developer and too opaque for a newcomer.

I fell into the first failure mode when I started documenting my own site. I kept wanting to explain why I made certain decisions, the thinking behind the architecture, the tradeoffs I considered. That's valuable context for a blog post. It's noise in a technical reference. Stripping that context out was the hardest editing I've done.

What language precision actually means in practice

Language precision isn't about vocabulary. It's about matching your language to the level of understanding your reader brings to the page. In other words, precision is a form of empathy.

Someone once told me that language precision is all about knowing your audience. But here's the tension: how do you truly understand your audience without knowing them in person?

In a product team, you don't guess. You work from user personas, documented profiles of your target readers. A Senior DevOps Engineer and a Marketing Manager are not the same reader, even if they're using the same product. The persona tells you what they already know, what they need to accomplish, and what language they speak. It turns an abstract audience into a concrete one.

Outside a product team, writing independently as I am, you build the persona yourself. You make educated assumptions based on who you expect to land on the page, and you write for that reader explicitly. The friction of writing for someone you can't meet is part of the job. The skill is in making your assumptions deliberate rather than accidental.

Progressive disclosure: one system, two readers

The developer and non-technical reader split doesn't always mean writing two separate documents. Great documentation systems use progressive disclosure, giving each reader what they need at the level they need it, within the same structure.

The developer gets the code sample immediately. The escort takes them straight to the destination.

The non-technical reader gets a link: "Read more about how this works." The tour guide is still available, just one step deeper.

This is the difference between documentation that serves one audience and documentation that scales. The escort and the tour guide don't have to be separate trips. They can be the same road with different lanes.

Quick win for systems thinkers

Before you write a single word, ask yourself one question.

Does my reader want to understand this, or do they want to use it?

Understanding means writing for the non-technical reader. Define terms. Build context. Surface assumptions. Tell the story.

Using means writing for the developer. Lead with the outcome. Trust the reader. Get out of the way.

And if your documentation needs to serve both, design for progressive disclosure. Give the developer the direct path. Give the non-technical reader the door to go deeper.

That one question and that one design principle will change how you approach every document you write.

What's next

In Part 5 we get into the anatomy of great documentation, what separates a document that works from one that merely exists. The difference shows up in the same three places every time.

I'm building a live example of developer-facing documentation as I write this series. MkDocs for Technical Writers is a practical guide to building and deploying documentation sites, and it's the direct result of everything this post describes.