Why Your Documentation Problem Is Actually a Process Problem

When a company decides its documentation is inadequate, the instinctive solution is to hire a technical writer. Get someone in who can write well, who understands the product, and who will own the documentation going forward.

Sometimes that works. More often, it doesn't — and the reason is almost always the same: the company has diagnosed a writing problem when the actual problem is a process problem.

What a Documentation Problem Usually Looks Like

I've walked into this situation multiple times. The symptoms are consistent:

Documentation exists, but it's scattered across Google Docs, Confluence spaces, Notion pages, and the occasional Slack thread that someone pinned. Nobody knows which version is current. The most accurate documentation is usually in someone's head.

Updates happen reactively. A client asks a question that exposes a gap, someone writes an answer, and that answer may or may not make it back to the official documentation. Features ship without documentation updates. Deprecations aren't announced clearly. New hires spend their first weeks asking questions that are answered in documents they didn't know existed.

The team knows this is a problem. They add "update docs" to sprint tasks and then deprioritize it when the sprint gets full. Which it always does.

Why Hiring a Writer Doesn't Fix It

A technical writer can produce excellent documentation. What they can't do is change the process around documentation — unless the organization is specifically giving them that mandate, which is rare.

The underlying issues that create bad documentation are:

Ownership is unclear. Who is responsible for ensuring a feature ships with current documentation? If the answer is "the technical writer," you have a bottleneck. If the answer is "whoever built it," you have a coordination problem. If the answer is "whoever notices it's wrong," you have a reactive system.

The deployment workflow is manual. Documentation that has to be exported, uploaded, or manually published creates friction. Friction creates avoidance. Avoidance creates drift.

There's no review process. Code gets reviewed before it ships. Documentation written after the fact, by the person who built the feature, reviewed by nobody, is a first draft presented as ground truth.

None of these are writing problems. They're process problems. A technical writer in this environment becomes a very skilled person playing an increasingly futile game of catch-up.

What the Process Fix Looks Like

At Griaule, I approached the documentation problem as a systems design problem, not a content problem.

The first question I asked wasn't "what needs to be written?" It was: "What does the path from 'feature exists' to 'documentation is live and accurate' currently look like — and where does it break?"

The answer revealed a system with no clearly defined path at all. The documentation step happened, if it happened, wherever there was slack in someone's schedule.

The fix had three components:

1. Make documentation part of the definition of done. A feature that ships without updated documentation isn't done. This is a process change, not a writing change — it requires agreement from engineering leadership, and it changes what counts as a completed ticket.

2. Remove deployment friction. The Docs-as-Code pipeline I built at Griaule automated the deployment step entirely. Writing a documentation update became as lightweight as writing a code comment. When the friction goes away, the avoidance goes down with it.

3. Create a review step. Documentation PRs went through the same review process as code PRs. This caught inaccuracies, improved clarity, and — perhaps most importantly — made documentation feel like real work product rather than an afterthought.

The result wasn't just better documentation. It was a system that produced better documentation consistently, without requiring heroic effort from any individual.

The Question to Ask Before Hiring

If you're evaluating whether to invest in documentation resources, the most useful diagnostic question isn't "how good is our documentation?" It's: "What is our current process for keeping documentation current, and where does it break down?"

If the answer is "we don't really have one," you need a process before you need a writer. Build the system first. Then the person you hire has something to work within rather than against.

The documentation is almost always a symptom. The process is usually the disease.