Most documentation is just digital landfill. I’ve watched teams burn weeks building sprawling wiki pages nobody ever opens. It’s not a tool problem—it’s a headspace problem. We write docs to feel busy, not to rescue the poor soul debugging at 2 AM. If you want your words to land, cut the fluff and zero in on what counts: solving a real problem, fast.
Start With the Outcome, Not the Feature
Engineers are wired to explain how things work. Readers? They don’t give a damn. They want to know what they can do and why they should care. I’ve gutted docs that opened with three paragraphs of architecture before hinting at which button to click. Nobody reads that stuff. They skim, skip the one step that actually matters, and ping you on Slack.
Flip the order. Put the finish line first. If your doc walks through setting up a CI pipeline, lead with: “In 10 minutes, your code deploys automatically on merge to main.” Then drop the steps. If there’s background they might need, shove it into a collapsible section or an appendix. 90% of readers won’t touch it, and that’s fine. The 10% who do are hunting a weird edge case, and they’ll be grateful for the breadcrumb.
Try this blunt test: grab any existing doc, skip the intro, and hand it to a fresh team member. If they finish the task without pinging you, you’ve won. If they mutter “I got lost at step 2,” your doc is broken. Delete the first two paragraphs and start over.
Write for the Tired, Distracted User
Your reader isn’t curled up in a quiet library with a latte. They’re on a rattling train, or their pager just screamed, or they’re patching a production meltdown while their boss stares over their shoulder. They’ve got about 30 seconds of focus. Your doc has to respect that.
Keep paragraphs stubby. Two or three sentences, tops. Bust up text walls with headings, code blocks, and bullet lists. I’ve stumbled on docs that are one unbroken slab of prose—nobody finishes those. They bounce. And once they bounce, they’ll tag your docs as “useless” and not bother next time.
Be blunt, not cute. Skip jargon unless it’s the exact phrase they’d search for. If your internal tool is called “Frobulator,” call it that, but explain it in one line: “Frobulator mashes three config files into one deploy-ready YAML.” Don’t make them guess. Skip the metaphors. Just say what the damn thing does.
Formatting beats grammar. A typo won’t kill a doc, but a missing code block will. If you’re showing a command, wrap it in a <pre> tag or a styled code block. If a step is easy to screw up, slap on bold or a warning emoji. Your job is to drop cognitive load, not chase a prose prize.
Structure Is Everything
I’ve learned that solid docs follow a familiar skeleton. It’s not a straitjacket—more like a set of habits. Here’s what I lean on for most technical pages:
- One-line summary: What this page does, in 10 words or less.
- Prerequisites: What they need installed, permissions, prior knowledge. Be blunt—if they need basic Python, say so.
- Steps: Numbered, one action per step. “Click the save button” is a step. “Configure the settings and then save” is two steps.
- Expected result: What should happen if they follow the steps. A screenshot often helps here.
- Troubleshooting: The top 2–3 things that go wrong, with the fix.
This skeleton works because it mirrors how people think. They scan prerequisites, follow the numbered list, and only peek at troubleshooting if something breaks. Don’t bury prerequisites in a paragraph. Don’t park the expected result at the top and force them to scroll back up. Order matters.
When you’ve got several related docs, cross-link them right where the question pops up. Not a “see also” graveyard at the bottom. If you mention a database migration, link to the migration guide right there. It’s a small move, but it keeps them in flow instead of opening a new tab and vanishing down a rabbit hole.
Kill the Passive Voice and “Best Practices”
Passive voice is the rot of technical writing. “The configuration file should be updated”—by whom? Me? A cron job? A vengeful spirit? Just say “Update the config file.” It’s shorter, sharper, and sounds like a person wrote it. I’ve bounced pull requests purely because the docs read like a corporate memo from 1998.
Also, ditch “best practices” unless you can back it up. If you write “use HTTPS for all endpoints” without saying why, it’s just noise. Instead, say “Use HTTPS because the load balancer strips HTTP headers.” Now it’s concrete. If there’s no actual reason, maybe it’s not a best practice—it’s just your preference. Own that.
Pick a side. If there are two ways to do something and one is clearly worse, say it. “You can use method A, but it’s slower and breaks on Tuesdays. Use method B.” Docs that try to stay neutral end up useless to everyone. Your reader wants a clear path, not a menu of choices they have to weigh while their system burns.
Test Your Docs Like You Test Your Code
Nobody nails docs on the first try. I’ve seen teams treat documentation like a checkbox: write it, merge it, forget it. Six months later, the steps are stale and someone’s cursing your name at midnight. Docs need upkeep, and they need testing.
Every time you onboard someone new, watch them use the docs. Don’t help. Just watch where they trip. Those trips are bugs in your documentation, and you should fix them right away. I’ve slashed onboarding time in half just by reworking three confusing sentences in a setup guide. The impact is that direct.
If you can’t watch someone live, at least slap on a feedback button. A bare “Was this page helpful? Yes/No” with a comment box will surface the worst pages. Most people won’t fill it out, but the ones who do are either furious or very thankful—both are useful signals. Act on the negative feedback within a week, or you’ll burn trust.
For docs that matter, do a quarterly review. Set a calendar nudge. Open the page, follow the steps yourself, and see if they still hold up. Stuff changes: APIs deprecate, UIs shift, config formats mutate. Your doc is a living thing, not a statue.
Real Example: A Bad README vs. a Good One
Let’s get concrete. Here’s a typical bad README I’ve bumped into on real projects:
This service provides a scalable solution for managing user authentication. It uses modern technologies to ensure smooth integration. To get started, you must first configure the environment variables which are vital for the operation of the system. It is recommended to follow established patterns when setting up the database.
What does that even say? Zero specifics. Zero steps. Zero value. I’d close that tab in three seconds.
Here’s what a good README looks like for the same service:
Auth Service
Handles user login, logout, and token refresh for the main app.Quick start
1. Clone the repo:git clone ...
2. Copy.env.exampleto.envand fill in your database URL and JWT secret.
3. Rundocker-compose up.
4. Visitlocalhost:3000/health—you should see{"status": "ok"}.Common issues
– Port conflict? Change thePORTvariable in.env.
– Database connection refused? Make sure Postgres is running and your URL includes the correct host.
See the gap? The good one tells you exactly what to do, what to expect, and what breaks. No fluff. Just the facts. That’s the bar I push for on every project.
Now, you might ask: does this actually shift behavior? Yes. I once picked up a codebase with a 40-page wiki nobody touched. I replaced it with a single-page setup guide following the skeleton above, plus a few linked deep-dives. Support tickets dropped 30% in a month. Engineers stopped interrupting each other. The docs became the first place people looked, because they finally worked.
FAQ
How long should a good documentation page be?
As short as it can be while still solving the problem. For a setup guide, aim for about one screen’s worth of text—roughly 300–500 words. For a concept explainer, maybe 800 words. If you’re blowing past 1500 words, split it into multiple pages or add a table of contents. Length isn’t a trophy; clarity is.
What’s the best tool for writing documentation?
Whatever your team will actually keep current. I’ve seen gorgeous docs in Notion rot because nobody wanted to open it. I’ve seen bare Markdown files in a repo stay fresh for years. Pick something that lives near the code (like a /docs folder) and can be reviewed in pull requests. Avoid tools that demand a separate login or a special CMS. Friction kills docs.
How do I convince my team to write better docs?
Skip the pep talk about the importance of documentation—that never sticks. Instead, lower the barrier. Create a template using the skeleton I mentioned above. Add a docs check to your PR template: “Does this change need a doc update? Link here.” Lead by example. When someone asks you a question in Slack, write the answer in a doc and link it. Over time, the culture tilts. People start linking to docs instead of re-explaining stuff, and that’s when it clicks.
Should I use screenshots in my docs?
Yes, but keep them lean. A screenshot of a UI can save a hundred words. But screenshots rot fast—a button moves, a label changes, and suddenly your doc is lying. Use them for complex interfaces where the visual layout matters. For terminal commands or code, never use screenshots; paste the text directly so users can copy it. And always add alt text that describes what the image shows, for accessibility and for those times the image fails to load.