Documentation has a window in the product development process. The heaviest work happens during Build. The window opens somewhere around Design and closes somewhere around Deliver. Everything before it is upstream. Everything after it is downstream.
Both sides generate knowledge that documentation needs. Neither reaches documentation by default. That’s not a communication problem or a staffing problem. It’s a structural one where the two directions fail in ways that are different enough to require different fixes.
Upstream: A Loss Problem
Upstream knowledge is generated at Discovery and early Design, before documentation enters the picture. By the time writers arrive, the reasoning behind product decisions has already been compressed. They’re written into formal documents, scattered across tools, or retained only in the memory of people who have since moved on.
The loss isn’t total, which is part of what makes it hard to see. Writers do typically receive some upstream documents: product requirements docs, Jira epics, finalized specs. These record conclusions — the what, the scope, what done looks like. What writers don’t typically receive are the working documents where the feature was actually being figured out: the page where three approaches were debated and two rejected, the doc where the PM worked through constraints before the requirements doc existed.
Those documents aren’t withheld. They’re just not part of any handoff and often not known to exist outside the small group who wrote them.
The distinction matters because conclusions and reasoning aren’t the same thing. A writer with the requirements doc knows what the feature does. A writer who also saw the earlier working documents understands why it works that way. That understanding shapes every judgment call about what to emphasize, what to explain, and what an edge case actually means for the reader.
That context serves the writer first. It doesn’t always belong in the documentation. What it does is make the documentation better in ways that aren’t always traceable back to the context directly.
Downstream: A Routing Problem
Downstream knowledge is different. It exists as support tickets, customer success call themes, bug reports, patterns of user confusion. After a product ships, there’s a steady stream of specific evidence about where documentation failed, where the product drifted from what the docs described, and where users built the wrong picture of how something works.
The problem isn’t that this evidence goes completely unnoticed. Some of it reaches the people maintaining the docs through a Slack message, a CS manager’s observation, a forwarded ticket, and so on. Some teams build a more deliberate way to receive it: a request form, a case system, a ticket type that anyone in the company can use to flag a gap. These help by giving the organization a defined channel and giving the content team somewhere to track what comes in.
But even a well-built request system captures individual problems, not patterns. One notification tells you one thing is wrong. It can’t tell you that the same three workflows have been generating the same confusion for six months, which is only visible when someone looks across many requests and reads them as documentation feedback. Most organizations don’t have a process that does that.
There’s a subtler problem too. When the channel is too slow or too high-friction, support teams don’t just stop submitting, they build their own fixes. A macro that resolves the ticket in two sentences. A private page with the workaround. A Slack snippet the whole team copies. These fixes work. They close the ticket. And because the ticket closes, the documentation team never sees it as a failure. The gap stays in the official documentation, unflagged, while the real answer circulates somewhere else entirely.
The Thread Between Them
The two failures feel like separate problems. One is about what happened before documentation entered the process. The other is about what happens after it ships. But they tend to land on the same content.
Documentation written without the upstream reasoning — built on conclusions rather than the full picture — is exactly the documentation most likely to confuse users downstream. And it’s the documentation least likely to get fixed, because the feedback that would flag the problem is unreliable. The two failures reinforce each other, around the same articles, for the same readers.
Neither fixes itself. Someone has to own the decision about what upstream context gets preserved before it disappears and make sure working documents, not just official ones, are part of what gets passed on. Someone has to own the process that returns downstream evidence to the people maintaining the docs, reliably enough to surface patterns rather than just individual complaints.
That’s the gap both articles return to. It’s worth keeping in mind as you read either one.