All articles

Nobody reads your documentation — and your activation rate proves it

Your docs are not bad. They are in the wrong place, written at the wrong altitude, and read at the wrong moment. Here is the anatomy of the gap — and the four behaviors that close it.

Maxence Rabrais — August 21, 2026 — 10 min read

Every SaaS company writes documentation. Almost every SaaS company watches users get stuck anyway. The two facts sit next to each other in every quarterly review, and the conclusion is almost always the same: we need better docs. It is the wrong conclusion. The docs are usually fine. The problem is that documentation asks the user to leave the product, translate their situation into a search query, read a general answer, and translate it back into specific clicks — at the exact moment they are least willing to do any of that.

This is a piece about that gap: where it opens, what it costs, why chat widgets did not close it, and what actually does.

The documentation paradox

Documentation has a structural problem that no amount of writing quality can fix. It is produced by people who understand the product completely, for people who understand it not at all, and it is consumed in a browser tab that is not the product.

Each of those three facts causes a specific failure.

Written by experts. The person writing the guide knows that "connect your workspace" means clicking the avatar, then Settings, then Integrations, then the third card. They write "connect your workspace" because to them, that is the instruction. The user reads it, looks at a screen with forty interactive elements, and does not see anything labelled "connect your workspace."

Written for a generic reader. Docs describe the product, not the user's account. They cannot say "you already added two seats, so the button you want is greyed out until you upgrade." They describe the happy path for a user who does not exist: no data yet, no half-finished configuration, no plan-specific restrictions.

Read somewhere else. The moment the user opens a documentation tab, they have left the workflow they were trying to complete. They have to hold their intent in working memory while reading prose. Most people cannot, so they skim, guess, and return to the product with a half-remembered instruction.

Where activation actually leaks

Onboarding funnels are usually instrumented at the wrong granularity. Teams measure signed up → activated, notice the drop, and conclude the product is too complex. But the drop is not one event. It is three distinct moments, and they fail for different reasons.

1. The first setup

The user has intent — they just signed up, they are motivated, they want to see the thing work. What they lack is orientation. They do not know which of the eight things on the screen is step one. This is the only moment where most products help at all, usually with a product tour: a sequence of tooltips that highlight elements in a fixed order.

Tours work when the user's situation matches the tour author's assumptions. They break the moment the user clicks somewhere unexpected, arrives with data already imported, or lands on a plan where step four is disabled.

2. The second workflow

This is the quiet killer. The user got through setup, saw a bit of value, and now wants to do the real thing they signed up for — the multi-step, conditional, genuinely complex workflow that your product exists to make possible.

Nobody tours the second workflow. It is too varied to script and too important to skip. So the user is handed to the documentation, and the paradox above takes over.

3. The feature they never find

The most expensive leak does not look like a leak, because the user never asks a question. They simply never discover the capability that would have made them a power user, and they renew at the lowest tier — or do not renew at all, because they never got far enough to see why the product was worth the money.

Why the chat widget did not fix this

The industry's answer for the last decade has been to put a chat widget in the corner. First staffed by humans, then by bots, now by LLMs with your docs in a vector store. It helped — a user who can ask a question in the product is better off than a user who cannot. But it did not close the gap, and the reason is precise.

A chatbot answers in a bubble. The work happens in the interface.

Ask a good documentation bot "how do I set up SSO?" and you get a correct, well-written, six-step answer. Now the user has to do the translation the bot skipped:

1. Read step one and hold it in memory.
2. Scan the interface for something matching the words in step one.
3. Guess which of two similar-looking buttons is meant.
4. Click, and see whether the resulting screen looks like what step two describes.
5. If it does not, decide whether they misread the answer or the answer is out of date.
6. Repeat for every remaining step, losing confidence each time.

That is the translation tax, and it is charged on every answer a chat widget gives. The bot has moved the documentation into the product without moving the work into the product.

A chatbot explains in a bubble. A Customer Success Manager gets it done — and neither the explanation nor the bubble was ever the point.

What we learned building Barkan

There is a second, subtler failure. A chatbot that reads your docs knows what the product does in general. It does not know what is on the user's screen right now: which plan they are on, which fields they already filled, which button is disabled and why. So its answers are confidently generic at exactly the moments users need something specific.

What a Customer Success Manager does differently

Every SaaS company already knows the solution, because they already deploy it — for their largest accounts. Give a customer a named human who knows the product, watches their usage, and jumps on a call to walk them through the hard parts, and that customer activates, expands, and stays.

Nobody has ever argued that model does not work. The argument has always been that it does not scale: you cannot put a human Customer Success Manager on a $99/month account and survive.

So the question is not whether the Customer Success Manager model works. It is which of its behaviors can be moved into software. There are four.

Knows

Not "has read the docs" — knows the live, rendered interface. What is actually on screen for this user, in this account, on this plan, right now. An answer grounded in the current DOM cannot be generically wrong the way a doc-trained bot can, because it is describing something it can see.

Shows

Instead of describing where a control is, point at it. A cursor that moves to the actual element, on the actual page, and waits. This is the step that deletes the translation tax: there is nothing to translate, because the instruction and the interface are the same object.

Acts

For workflows that are well understood and safe, do the thing. Fill the fields, click through the sequence, navigate the pages. The user says what they want in their own words and watches it happen, which is a fundamentally different experience from being taught how to do it themselves.

This is also where trust is won or lost, which is why anything destructive or expensive should stop and ask before it happens rather than after.

Watches

The behavior that separates a Customer Success Manager from a help desk: nobody had to ask. A good CSM notices that a customer finished setup but never turned on the feature their use case depends on, and reaches out. That is a proactive motion driven by usage signals, and it is the one that produces expansion revenue rather than deflected tickets.

Docs, chatbot, Customer Success Manager

The three approaches are often compared as if they were competing answers to the same question. They are not — they answer different questions, and only one of them answers the question the stuck user is actually asking.

The row that matters most is the last one. Documentation and chat widgets are both reactive: they require a user who knows they are stuck, is willing to ask, and can phrase the question. Every user who quietly gives up is invisible to both.

Doing this without rebuilding your product

The reasonable objection at this point is that all of the above sounds like a rewrite. It is not, and it should not be — a guidance layer that requires you to restructure your application is a guidance layer nobody will adopt.

The install is one script tag in the layout you already render on every route:

<script async src="https://trybarkan.com/widget.js" data-barkan-site="site_your_key"></script>

That is the whole integration. No component wrapper, no route annotations, no tour scripts to write and re-record every time the UI changes. The widget mounts its own root with isolated styles, reads the rendered interface, and starts answering.

1 script tag

to install, in the layout you already have

20,000

guided answers a month on the Max plan

7 days

free trial, no card required

The metrics that actually move

If you deploy this and want to know whether it worked, the headline metric is not "questions answered." That number goes up immediately and means very little. Watch these instead:

• Time to first meaningful action. Not signup-to-login; signup-to-the-thing-your-product-is-for.
• Second-workflow completion. The percentage of users who complete a complex workflow after their first successful one. This is the number that documentation never moves.
• How-to ticket share. Not total tickets — the share of your queue that is "how do I", versus bugs and billing. A guidance layer should collapse the first category and leave the others untouched.
• Feature discovery per account. How many distinct capabilities an account touches in its first 30 days. This is the leading indicator for expansion.

If the first three move and the fourth does not, you have built a better help desk. The fourth one moving is what tells you the Customer Success Manager behavior — the watching — is actually working.

Documentation is not going away, and it should not. It is the reference layer, and reference layers are valuable to the people who want them: developers integrating your API, admins planning a rollout, the occasional user who genuinely prefers to read.

But for the user who is stuck at 4pm with a half-finished workflow and a deadline, the answer was never a better article. It was someone who knows the product, can see their screen, and will show them — or just do it.