I used to write technical documentation for clients the way I'd write it for myself: an architecture overview, environment variables, a deployment runbook, the database schema. Forty pages of accurate, well-organized engineering reference. Then a client emailed me three weeks after handover asking how to change the phone number in the site footer. The answer was on page 12 of the doc he paid for. He never opened it, because nothing in it was written for him. That was the lesson: a document a client reads answers the client's questions, in the client's language, at the moment they need them. Everything else is a document I wrote to feel thorough.
The fix is not writing more. It is writing two different things and being honest about who each one is for. The client who signed the invoice almost never needs my deployment pipeline. They need to add a blog post, reset a password, and read the analytics without messaging me. Separate those concerns and your docs get read, your inbox goes quiet, and clients come back because working with you felt effortless.
Who is actually going to open this document?
Before I write a word I name the reader. On most projects there are two, and they want opposite things. The non-technical client owner wants to operate the thing I built: publish content, manage users, find a number in a report. The future developer (sometimes me in six months, sometimes whoever inherits the project) wants to run it locally, understand the architecture, and deploy a change safely. If I mix those audiences into one file, the client drowns in Docker commands and the developer wades through screenshots of a WYSIWYG editor. Two readers, two documents.
- User docs (the client owner): how do I add a blog post, reset a password, add a team member, read last month's traffic, take a backup. Plain language, no jargon, screenshots.
- Developer docs (whoever maintains the code): local setup, environment variables, build and deploy, third-party keys, the gotchas that will bite at 2am. This is the README and the architecture notes.
- A one-page quickstart that sits in front of both and answers the five things every reader needs in the first five minutes: where the site is, where the admin login is, who to contact, where the rest of the docs live.
Naming the reader is the same discipline I lean on in managing client expectations on fixed-price work: you decide what the other person actually needs before you decide what to deliver. Docs are part of the deliverable, not an afterthought stapled to it.
What does a structure that gets read look like?
Task-oriented headings, phrased as the exact question the client would ask. Not "Content Management" but "How do I add a blog post?" The client searches the page (Ctrl+F) for the words in their head, and those words are "add blog post," not "content management subsystem." Under each heading: short numbered steps, one action per step, and a screenshot for anything visual. If a step has a gotcha ("the image must be under 2MB or the upload silently fails"), it goes inline at that step, not in a separate notes section nobody reaches.
Here is the skeleton I reuse for the user-facing doc on almost every project. I keep it as a template file and fill it in as I build each feature.
# [Project] — Owner's Guide
## Quickstart (read this first)
- Live site: https://...
- Admin login: https://.../admin
- Your username: ...
- Support contact: you@example.com (response time: 1 business day)
- Full guide below, organized by task.
## How do I log in and reset my password?
1. Go to https://.../admin
2. ...
## How do I add or edit a blog post?
1. ... (screenshot)
2. ... Note: images must be under 2MB.
## How do I add a team member?
1. ...
## How do I read the analytics?
1. ... What "sessions" vs "users" means: ...
## How do I take a backup / what happens if something breaks?
- Backups run nightly. To restore, contact me.
## Glossary (plain-language)
- Slug: the part of the web address after the last slash.
- ...
How do I keep the docs from rotting?
Documentation goes stale the instant it lives somewhere the code doesn't. The most maintainable docs I write are the ones that travel with the project: the developer guide is the repo's README and a /docs folder; the client guide is either a Markdown file in the same repo or a single page inside the app's admin panel, so it is one click from where they're working. Both are version-controlled, which means I can see when a doc last changed and diff it against a feature. Treating docs as part of the codebase is the same instinct behind a clean Git branching strategy for solo and small teams: if it isn't in version control, it doesn't really exist.
The other half is timing. I write docs as I build, not at the end. When I finish the "add a blog post" feature, I write the "how do I add a blog post" section that same afternoon, while the clicks are fresh and the screenshots match the current UI. Documentation written in the last billable hour before handover is always thin, always wrong about the small things, and always shows it.
- Do write headings as the literal question the client will ask, so search finds them.
- Do put the gotcha inline at the step it affects, not in a separate caveats section.
- Do include a one-page quickstart up front; many clients never read past it, and that's fine if it's good.
- Don't paste your architecture diagram into the client's guide — it answers a question they never have.
- Don't use internal jargon without a plain-language glossary entry the first time it appears.
- Don't write it all at the end; write each section as you ship the feature it documents.
Good docs are cheaper than support. Every question your guide answers is an email you don't get, a follow-up call you don't take, and a small reason the client trusts you enough to hire you again.
Does this actually pay off?
It does, and it's measurable. On a content site I handed over with a real task-oriented owner's guide, support messages in the first month dropped from the usual handful per week to two total, and one of those was a thank-you. That quiet inbox is unpaid time I got back, but the bigger return is repeat business: the client who can operate what you built without friction is the client who comes back for phase two and refers you to the person at the next desk. Documentation is also one of the most underrated things you can show off. A clean handover guide is portfolio material in its own right, and I treat it that way in my developer portfolio that gets you hired.
Write for the person who paid you, not the person you wish they were. Name the reader, phrase every heading as their question, keep the file next to the code, and write it as you build. Do that and the forty-page reference becomes a six-page guide they actually open — and the footer-phone-number email never lands in your inbox.
