Most documentation is just theater. It’s there because a manager decided it should be, not because it solves a real problem. I’ve lost count of the READMEs that are nothing but a brick of setup commands, API references structured like a phonebook, and internal wikis nobody visits twice. The issue isn’t that engineers can’t write—it’s that we treat docs like a box to check before sprint close.
When docs actually work, though, they’re a force multiplier. Good ones slash support tickets, cut onboarding time in half, and keep your Slack from turning into an unpaid help desk. The secret is simple: write for a real person who’s tired, distracted, and just wants to finish a task. Here’s how I do it, shaped by too many years of building dev tools and mopping up other people’s messes.
Start with the Job, Not the Tool
Engineers love describing how things tick under the hood. That’s a documentation killer. Nobody clicks a guide to admire your architecture. They click because they need to do something—deploy a container, fix a busted config, integrate an API. If your opening paragraph doesn’t spell out what they’ll achieve and why it matters, you’ve already lost them.
I build every doc around a user story: “As a [role], I want to [do something] so that [I get a result].” Like, “As a junior backend dev, I want to spin up the staging database locally so I can test queries without blowing up production.” That single sentence steers the whole page. It forces me to include only what’s needed and chuck the fluff about design backstory or past decisions. Save the origin tales for a blog post.
The 5-Minute Rule
When someone hits your docs, they should find their answer or finish a basic task inside five minutes. If they can’t, your structure is broken. I use a dead-simple test: give the page to a teammate who’s never touched the feature, set a five-minute timer, and shut up. If they scroll more than once, the info hierarchy is off. Headings need to be scannable, steps numbered, and code snippets copy-paste ready—no lazy placeholders like your-api-key-here without a real example right next to it.
Write Like You’re Debugging at 2 a.m.
Docs get read under pressure. The reader’s production is on fire, their deadline is breathing down their neck, or they’re just annoyed with your product. So your tone has to be blunt, steady, and jargon-free. I avoid adjectives unless they earn their keep. Telling someone to “simply run the following command” is a straight-up lie if the command has six flags and a YAML file. Instead, I’ll say, “Run this command. If you hit error X, see the troubleshooting section.”
Passive voice is another foe. “The configuration file must be edited” hides who does the work. “Edit the config file at /etc/app/config.yml” is clear and actionable. Every sentence should either instruct, explain a result, or answer a likely question. If a paragraph doesn’t do one of those three, I cut it. No mercy.
Examples Over Explanation
A developer’s brain latches onto patterns. I can write three paragraphs about how an API endpoint paginates results, or I can show a single curl request with the response. The latter wins, every time. Examples aren’t just decoration—they’re the main event. I put them up front: the first thing you see in my docs is a working code block, then a breakdown of what each piece does. This holds for APIs, CLI tools, even fuzzy conceptual topics. For something like “How Caching Works in Our System,” I’d open with a sequence diagram or a before-and-after latency log, then explain the mechanics.
Maintenance Is Part of Writing
Outdated docs are worse than no docs at all. They breed distrust and chew up time. I’ve watched teams pour weeks into a launch guide only to let it rot for half a year. When a new hire follows it and hits wall after wall, they learn to ignore everything you’ve written. That’s a culture problem, not a tech one.
I treat documentation like code: version it, review it in pull requests, and test it. For procedural docs, that means running the commands verbatim in a clean environment. If a step fails, the doc doesn’t merge. Yeah, it’s a bit tedious, but it catches drift early—like when a dependency shifts or a UI gets a facelift. For bigger projects, I schedule a quarterly “doc audit” where I hit the most-visited pages, verify accuracy, and prune anything that’s gone stale.
Link to Living Sources
Nothing ages faster than a UI screenshot or a hardcoded version number. Where I can, I link to the source of truth: a config file in the repo, a live API spec, a relevant changelog. For CLI tools, I lean on the --help output as the canonical reference and show only the most common flags in the doc. This keeps the surface area small and cuts the risk of contradictions.
Structure for Skimmers
Nobody reads docs cover to cover. They jump to what looks like the answer and bail if it’s not there. I design pages with that behavior in mind. Every major section gets a descriptive heading that could stand on its own in a search result. Subheadings break up the monotony. Bullet points and numbered lists do the heavy lifting for procedural content. When I review a draft, I strip out the body text and look only at the headings and lists—if that skeleton makes sense, the page will hold up.
I also steer clear of deep nesting. More than three heading levels (h2, h3, h4) is a signal that the page is trying to juggle too much. Split it into separate pages and link them together. A decent rule of thumb: each page should solve one problem. If you’ve crammed “Installation,” “Configuration,” and “Troubleshooting” onto one page, break them apart and use a sidebar for navigation.
Use the Inverted Pyramid
Journalists put the most newsworthy info first. I do the same with docs. The title tells you what the page does. The first sentence tells you the outcome. The first code block shows the happy path. Details, edge cases, and alternatives come later. That way, even if someone bounces after 30 seconds, they’ve still picked up something useful. I picked this up from working on public-facing API docs: median time on page was under two minutes, so those first 200 words had to carry the whole load.
FAQ: Documentation That Sticks
What’s the biggest mistake in technical docs?
Assuming too much. I’ve tripped over guides that start with “First, set up your Kubernetes cluster” like that’s a five-minute job. Always define your audience explicitly and spell out prerequisites. If you’re writing for someone who’s never touched Docker, don’t just toss them a link to the Docker docs—give them the exact commands to reach the starting line. Over-explaining beats leaving people stranded every time.
How do I convince my team to prioritize documentation?
Show them the bill. Track how many support tickets a decent FAQ could have dodged, or clock how long a new hire takes to ship their first change without docs. Put numbers on the table. Then pitch a small, specific fix: document one high-pain topic and measure the result. Once you’ve got a win under your belt, it’s easier to nudge toward a doc-first culture. I’ve found that baking docs into the definition-of-done for features is the only approach that actually lasts.
Should I use video or text for documentation?
Text, almost always. Video is a pain to update, impossible to search, and slow to skim. I only use video for high-level overviews or demos where seeing the interface matters. Even then, I pair it with a text summary and timestamps. The exception is when your product is inherently visual—like a design tool—but even there, text instructions for common tasks are faster to follow.
How do I handle documentation for internal vs. external audiences?
Same principles, but internal docs can get away with more bluntness. You can say, “This legacy service is a dumpster fire; here’s how to keep it breathing” because the audience shares your context. External docs need a bit more polish and can’t air the dirty laundry. The structure doesn’t budge: tasks first, explanations second, and always a clear path to a human if the doc fails. I keep a shared channel linked at the bottom of every internal page so people know where to ask.
Closing the Loop
Writing documentation that people actually read isn’t about sounding smart. It’s about respecting the reader’s time and mental state. Be specific, be blunt, and test everything you write. If you do that, your docs will earn trust—and trust is what keeps people coming back. Next time you’re tempted to add another paragraph of context, ask yourself: would I read this at 2 a.m. while on call? If the answer’s no, chop it.