Earlier this year I documented douglasebhoman.com, my personal portfolio site. I built it. Every line of HTML, every CSS variable, every deployment pipeline. 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.
The tour guide and the precision guide
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, 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:
GET /users/{id}
Returns a single user object.
Parameters: id (string, required)
Response: 200 OK
{
"id": "abc123",
"name": "Douglas Ebhoman"
}
“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.
Where technical writers most often get this wrong
There are two failure modes and most writers fall into one of them. 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. The result is documentation that wastes their time and signals clearly that the writer doesn’t understand who they’re writing for.
The second failure mode is the mirror: 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 intimidates rather than informs.
I fell into the first failure mode when I started documenting my own site. I kept wanting to explain why I made certain decisions. 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 a product team, 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.
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 precision guide takes them straight to the destination. The non-technical reader gets a link: “Read more about how this works.”
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.
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.
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.
Discussion