Help Document

When a product has ten features, answering questions one at a time works fine. Someone on the team writes out the steps in a reply and that's the end of it. Once the same question shows up twenty times a week, the arrangement breaks down. Every reply gets written from scratch, the explanation shifts a little depending on who types it, and the menu name in last week's reply has already been renamed by this week's release.

Pagedeck hit exactly that. Of the six support tickets Sofia opened one morning — a ticket being a single logged customer request — four asked how to give a teammate edit permission. She pasted an older colleague's reply into two of them, and because that reply described a screen from three months earlier, both customers wrote back saying the menu didn't exist. Writing the same explanation six times was the smaller problem. The larger one was that all six came out slightly different and two of them were wrong.

A help document is the fix that turns that reply into something written once and used many times. Put one version at a fixed address and the explanation converges; when the screen changes, there is one place to correct. Nobody has to be present to teach, and the cost is identical whether ten people read it or ten thousand. That last part is what separates it from a training session, where a team member runs the lesson live at a scheduled time.

A single document is usually built from six pieces. Each one has a predictable kind of ticket that comes back when it's missing.

1. Title. Write it in the words a customer would actually type into a search box. "Give a teammate edit permission" gets found; "Permission management," the name used internally, does not.
2. Audience and prerequisites. Say up front who is allowed to do this. If a setting is admin-only and the document doesn't mention it, a regular member follows four steps, can't find the button on the fifth, and files a ticket.
3. Steps. A numbered sequence with exactly one action per step. "Pick your team under Settings, then choose Edit on the Permissions tab" gets split into two. Pack two actions into one line and readers lose track of where they are.
4. Screenshots. A picture beats prose for showing where a button lives. "Top right" moves around depending on window width, and the customer clicks something else.
5. What to do when it doesn't work. Two or three common sticking points with what to check at each. A document without this section sends every customer who drifts off the path straight back into the queue.
6. The last-updated date. It's how a reader decides whether to trust the instructions. A date two years old makes people close the tab halfway through.

The third and fifth pieces are where the real work sits. Steps and failure points don't come out of anyone's head — they only appear when the writer clicks through the feature while writing.

Who writes depends on the size of the company. Early on it's whoever built the feature: the product manager who wrote the spec, or the engineer who implemented it, since they know the behavior most precisely. Once the library runs into the hundreds, a dedicated role appears — the technical writer, someone whose full-time job is product instructions and who also pulls the terminology and voice of scattered documents into one consistent set.

Pagedeck has no dedicated writer yet, so two people split it. Mia drafts the steps as she ships a feature, and Sofia appends the places customers actually get stuck as tickets come in.

There are two kinds of readers. The first is the customer. Nobody starts at document one and reads forward; almost everyone lands on a single page through search at the moment something breaks. So each document has to make sense on its own. A sentence like "using the team you created in the previous article" stops anyone who arrived without reading that one.

The second reader is internal. Instead of rewriting the explanation, Sofia drops a link into her reply. The document is customer-facing and support material at the same time, which is why its accuracy translates directly into how fast tickets close.

"That's the fourth time this week. It'd be faster to just write a help doc."

Rather than retyping the same reply, write it once and pin it somewhere fixed.

"I sent them the link and they still came back. Step 3 doesn't match the current screen."

The document exists but wasn't updated after a release, so it sent the customer in the wrong direction.

"The settings screen changes next week — can you pull the list of docs we need to touch first?"

Find the affected documents before the release ships, which is a routine move whenever a screen is changing.

All three showed up in the same week at Pagedeck, while the permissions screen was being rebuilt. Mia shared the release date, Sofia came back with the seven documents that touch permissions, and it became clear on the spot that four of them only needed new screenshots while three had steps that no longer applied. The team fixed those three first and swapped them in the morning of the release.

The release communication telling existing customers what was changing went out the same week. The announcement says that something is changing, the document says how the new version works, so the announcement links into the document. Reverse that order — announcement first, document still showing the old screen — and every customer who follows the link runs straight into wrong instructions.

The most common assumption is that writing documents makes tickets go down by itself. Since the tickets are what prompted the writing, that expectation makes sense. In practice the volume only drops if customers actually reach the page. Give it a title nobody searches for, or link it from nowhere inside the product, and you end up with a document and the same ticket count. Six months of that and the person writing them concludes documentation doesn't work and stops. The thing to fix isn't the writing — it's the path that leads to it.

The second mistake is treating a document as an asset that's finished once written. It's text, so it feels permanent, but the screens it describes keep moving. A wrong document is worse than no document. With no document a customer files a ticket immediately; with a wrong one they spend time following instructions that fail, and then file the ticket anyway. So any plan to grow the number of documents budgets time for maintaining them too.