Why Your Best Engineers Write the Worst Documentation (And How to Fix It)

I've been staring at this problem for three years now. The senior engineer on my team, the one who architected our entire event-driven system, the person I go to when I'm stuck on anything, writes documentation that reads like encrypted messages from another dimension.

Meanwhile, our junior dev who joined six months ago? His docs are clear, helpful, and actually get read.

Not a fluke. It's a pattern I've seen at every company I've worked at, and it reveals something broken about how we approach technical documentation best practices for software teams.

Here's what I've come to believe: the problem isn't lazy developers. We've built documentation systems that actively fight against how developers think and work. We've borrowed processes from technical writing that make sense for user manuals but create friction for engineers. And then we wonder why nobody updates the docs.

In this piece, I'm going to walk through why this happens and, more importantly, what actually works. I've watched teams go from documentation wastelands to having docs that people genuinely reference. The fixes aren't complicated, but they require us to stop pretending developers will become technical writers.

When Best Practices Backfire: The Hidden Mismatch

Traditional technical writing advice sounds reasonable on paper. Write complete sentences. Use a formal tone. Structure content in a logical hierarchy. Include comprehensive context.

The problem? Developers don't process information that way.

When I'm debugging a production issue at 2 AM, I don't want a beautifully written essay explaining the philosophy behind our authentication system. I want to know which endpoint to hit and what headers it expects. Right now.

The mismatch runs deep. Technical writing best practices assume readers start at the beginning and read sequentially. Developers jump in at random points, scan for specific information, and leave the moment they find it. Or don't find it.

I remember spending twenty minutes writing context-rich documentation for a new API endpoint. Complete background, use cases, related systems. The whole thing. A week later, my teammate asked me the same question the docs answered in paragraph three. He'd opened the page, skimmed for two seconds, and bounced.

That's when I realized: my docs were written for someone who wanted to learn. Real usage is about someone who wants to do.

Expert developers make this worse through the curse of knowledge. They literally can't remember what it felt like to not understand something. So they skip explanations that seem obvious to them, creating documentation that only makes sense to people who already know the answer.

Why do developers skip reading documentation in the first place? Because we've trained them to. Most docs are either outdated, incomplete, or buried somewhere nobody can find. After getting burned a few times, developers learn it's faster to just ping someone on Slack.

Docs-as-Code: Making Documentation Feel Like Engineering

The single biggest shift I've seen work is treating docs like code. Not as a metaphor. Literally.

A docs-as-code workflow for engineering teams means documentation lives in the same repo as the code it describes. It goes through pull requests. It has linting. It gets reviewed alongside the code changes it documents.

Why does this approach work? It removes context switching. When I'm already in VS Code fixing a bug, adding a doc update to my PR feels natural. Opening Confluence, navigating to the right page, figuring out the formatting: that's a completely different mental mode.

At my company, we moved our API docs into Markdown files next to the code about eight months ago. In my experience, documentation updates in PRs increased significantly. I'd estimate we went from maybe 5% to somewhere around 40%. Not because anyone lectured people about documentation importance. The friction just disappeared.

Here's what the workflow looks like:

Same review process. Docs get PR reviews just like code. Reviews catch errors and keep people honest about whether the docs actually match the implementation.

Version controlled. When someone asks "what did this endpoint do six months ago?" we can actually answer that. No more archaeology through Confluence edit history.

CI integration. We run spell checkers, link validators, and formatting checks automatically. Broken docs fail the build.

Proximity. Docs live next to the code they describe. When you change the code, you see the docs right there. It's a subtle reminder that works better than any policy.

Tools matter less than the principle. Whether you use MkDocs, Docusaurus, or just plain Markdown files, the point is meeting developers where they already work.

Structure for Scanners: Formatting API Docs That Actually Get Read

Let's talk about how to structure API documentation for readability, because I got this wrong for a long time.

I used to write documentation like I was explaining something to a friend. Conversational. Contextual. Lots of "and then you'll want to" transitions.

Developers don't read like that. They scan.

Eye-tracking studies on how users read web pages show an F-pattern scanning behavior. Readers look at the first line, maybe the second, then scan down the left side looking for keywords. If they don't find what they need in seconds, they leave. Developers reading documentation aren't immune to this; they scan just like everyone else.

So structure isn't about logical flow. It's about making information findable.

What actually works:

Lead with the what, not the why. Put the endpoint, method, and basic usage right at the top. Context comes after, for people who want it.

Use consistent headers. Every API doc should have the same sections in the same order: request format, response format, errors, examples. No surprises.

Code examples first. A working cURL command tells developers more in three seconds than three paragraphs of explanation. I always include copy-paste examples that actually work.

Tables for parameters. Don't bury parameters in prose. A table with name, type, required, and description columns lets developers scan instantly.

Error states get their own section. What happens when things go wrong is usually what developers are searching for.

Here's a developer-friendly documentation example structure I've landed on:

## Create User

POST /api/v1/users

Creates a new user account.

### Quick Example

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "name": "Test User"}'

Request Body

Field	Type	Required	Description
email	string	yes	User's email address
name	string	yes	Display name
role	string	no	Defaults to "member"

Response

... and so on

Notice what's not there? No introduction explaining what users are. No background on our authentication philosophy. That stuff can exist somewhere, but not blocking the developer who just needs to make the request work.

## The Lazy Developer Test: Path of Least Resistance

Here's my operating theory: developers will document if documenting is easier than not documenting.

Sounds circular, but hear me out. When someone asks me a question on Slack, I could answer directly, or I could write a doc and send them the link. The first option is almost always faster, so the first option wins.

But what if creating that doc took 30 seconds? What if there was a template already there, and I just filled in the blanks?

Developer documentation templates that increase adoption work because they eliminate the "staring at a blank page" problem. Nobody wants to decide how to structure something when they're already mentally exhausted from the actual work.

Templates I've seen work best are almost aggressively simple:

**For runbooks:**
```markdown
# [Service Name]: [Problem Type]

## Symptoms
What does this look like?

## Cause
Why does this happen?

## Fix
Step by step, what do I do?

## Prevention
How do we stop this from recurring?

For architecture decisions:

# [Decision Title]

## Context
What situation led to this decision?

## Decision
What did we decide?

## Consequences
What trade-offs did we accept?

For onboarding a new service:

# [Service Name]

## What it does (one sentence)

## How to run it locally

## Key endpoints

## Common issues

Specificity matters. "Add documentation" is overwhelming. "Fill in these five fields" is doable.

Some documentation tools developers prefer in 2024 make this even easier: Notion templates, GitHub issue templates, even simple scripts that generate skeleton docs. The tooling keeps getting better.

But honestly? A Markdown file with headings works fine. Don't let tooling decisions become another reason to delay.

Case Study: A Documentation Transformation

I want to share what happened at a team I worked with last year, because it shows how these ideas compound.

They had a typical documentation situation, which is to say, a disaster. Docs existed in three different places. Most were out of date. For months, the team lead had been asking people to "please update documentation" in standups with zero effect.

What changed:

Month 1: Consolidation. They picked one place for docs. Just one. Everything else got deprecated. Harder politically than technically, but it mattered. When there's one source of truth, it's either right or wrong. No ambiguity.

Month 2: Proximity. They moved documentation into the code repos. API docs next to API code. Runbooks next to infrastructure config. Immediately, documentation connected to work people were already doing.

Month 3: Templates. They created five templates covering 90% of their documentation needs: service overview, API endpoint, runbook, architecture decision, and meeting notes. Nothing fancy.

Month 4: Review integration. PR reviews started including a docs checkbox. Not enforced automatically, just present. Social pressure did the rest.

Month 5: Celebration. They started shouting out good documentation in their team channel. Sounds cheesy. It worked. People started trying to get their docs recognized.

Month 6: Measurement. They tracked the percentage of PRs with code changes that also updated related docs. They published it on their team dashboard.

By month six, the team saw a dramatic improvement in documentation coverage. PRs that touched code with documentation were far more likely to update that documentation. The team estimated the rate went from roughly 10-15% to somewhere around 85-90%. Exact numbers varied, but the transformation was unmistakable.

No grand initiative. No new hires. Just systematic friction removal over six months.

[Link: improving developer experience through better documentation]

Your First Month: A Practical Playbook

Look, I'm not going to pretend this is easy. Changing team habits never is. But I've seen these steps work, and they don't require anyone's permission.

Week 1: Audit. Find where your docs actually live. All of them. Make a list. Don't judge yet, just inventory.

Week 2: Consolidate. Pick one source of truth. Start redirecting people there. Archive everything else with clear "this is outdated" notices.

Week 3: Migrate critical docs. Move your most-referenced documentation into your code repos if it isn't there already. Start with API docs or runbooks.

Week 4: Templates. Create three simple templates based on what your team documents most often. Share them. Use them yourself first.

After that first month, momentum builds. Add PR integration. Experiment with linting and automated checks. Celebrate wins publicly.

Technical documentation best practices for software teams that actually work aren't the ones you read in style guides. They're the ones that acknowledge developers are busy, cognitively loaded, and operating under constraints. Meet them where they are.

Your best developers write terrible documentation because we've given them terrible systems. Fix the systems, and the documentation follows.

Now I'm curious: what does your team's documentation situation look like? Is it the Wild West? Have you tried any of these approaches? I'm always updating my thinking on this stuff, and I genuinely learn from what other teams are doing.

---

If you want more on technical writing tips for engineers who hate writing, I cover this stuff occasionally in my newsletter. No pressure, but it's there if backend engineering patterns interest you.