You’re thirty minutes into a conversation with an engineer who has mentally moved on to the next feature. You’re asking about a decision that was made four months ago. They remember the outcome. The reasoning is hazier. They think there was a constraint — something to do with how a third-party supplier handles a specific fare class — but they’d have to dig through old Slack threads to confirm, and that Slack thread is buried three months back, if it still exists at all.
What you’re doing in this conversation isn’t research. It’s archaeology. You’re not learning something new. You’re trying to recover something that existed, was discussed at length, shaped a product decision, and was never written down in a form that survived.
What’s left are conclusions. The argument that produced them is gone.
The resulting documentation will be accurate. It will describe what the product does. What it may not be able to do is account for why — why this constraint shapes the behavior, why this edge case is handled the way it is, why the design went this way and not another. That gap isn’t a writing failure. It’s a knowledge loss that happened before you entered the room.
This is the upstream context problem. Writers (content owners such as technical writers, UX writers, and content designers) often do arrive late. But that’s not the root of it. By the time writers arrive, the reasoning behind product decisions has already been compressed out of reach. What’s left are conclusions. The argument that produced them is gone.
Where the Loss Happens
Knowledge doesn’t disappear all at once when writers show up. It degrades at each stage of the product development process, compressed and summarized as it moves forward, so that by the time it reaches a writer it’s a much thinner version of what it started as.
Discovery
Discovery is the richest reasoning moment in the entire process. This is where the problem gets defined, where research gets synthesized, where constraints get established. These are the “why this and not something else” conversations that will shape every decision that follows.
Almost none of it gets formally captured in a way that survives the stage. Writers are almost never present. By the time a feature reaches Design, the Discovery reasoning has become a set of shared assumptions the team carries without anyone having written them down.
Design
Design is where competing approaches get debated and resolved. This is the pre-PRD layer: the Confluence page tracking three approaches before one was chosen, the Notion doc where the PM worked through constraints, the draft shared in a Slack channel for feedback before anyone called it official.
These are the documents where the reasoning actually lives, where the tradeoffs considered, the alternatives rejected, the constraints that ruled certain paths out. In theory they exist. In practice they’re often not shared beyond the small group who wrote them, not findable from outside that group, and not part of any standard handoff.
Formal documents
Formal docs, such as product requirements docs (PRDs), Jira epics, are the conclusions from Design, written up. Writers can usually access these. They’re the official record of what’s being built: scope, acceptance criteria, the what. The reasoning that produced them is in the working documents from the previous stage, or it’s gone.
Build
Build is where writers typically enter the process. By this point they’re receiving a summary of a summary. The Jira ticket references the requirements doc. The requirements doc referenced the design brief. The design brief referenced conversations that weren’t written down. Each stage handed forward less than it received.
Build is also where writers typically get access to a staging environment, and for understanding how a feature actually behaves, it’s one of the most reliable sources available.
A staging environment shows you what was built rather than what was planned, which aren’t always the same thing. It also places the feature in context: how it connects to adjacent features, what it assumes the user already knows, where the natural entry and exit points are. That spatial understanding is difficult to get from a document. Using the feature puts you in the user’s position in a way that reading a spec doesn’t. More on that in the next section.
SME interviews
SME interviews are the reconstruction phase: the moment when writers try to recover what the chain compressed. What can be recovered is real but limited. It’s shaped by what the engineer remembers, what they think is relevant, how much time they have, and how well they can surface reasoning they’ve long since internalized. What took months to establish gets compressed into thirty minutes. Nuance doesn’t survive that ratio.
The chain matters because it shows that late entry is a symptom, not the root cause. Even a writer who entered at the very start of Design would still miss the Discovery reasoning. Even a writer present for every design conversation would still find that working documents from early in that stage don’t make it into standard handoffs.
The compression happens continuously, at every stage, driven by how each stage hands knowledge forward — not by when writers arrive.
What Writers Can Access and What They Can’t
The upstream loss isn’t total. Part of what makes it hard to diagnose is that writers do receive upstream documents. The problem is which documents they receive, and what those documents contain.
What’s typically accessible: product requirements docs, Jira epics, Figma design files, API contracts generated from code. Formal, official, findable. The decisions.
What’s typically not accessible: the working documents where those decisions were worked out. The Confluence page that became the requirements doc. The Notion doc that became the design brief. The Google Doc where the PM first drafted the problem statement before it became anything official. These aren’t withheld. They’re not part of any handoff because they were never part of any handoff process. They’re often not known to exist by anyone outside the small group who wrote them.
Official documents record what was decided. Working documents record why.
The distinction matters because official documents and working documents contain different things. Official documents record what was decided. Working documents record why: the constraints that ruled out alternatives, the tradeoffs that shaped the outcome, the edge cases that were knowingly deferred, the approaches that were tried and abandoned.
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.
At Wayfarer, when a new Desk feature goes into development, writers learn about it through engineering handoffs and design reviews. The requirements doc exists and is accessible. The earlier scoping documents where the feature’s shape was actually worked out, where alternatives were weighed, aren’t shared as a matter of course. They may not be findable even when they exist.
What the Gap Actually Costs
The case for upstream context is sometimes framed as: documentation should contain more background, more reasoning, more “why.” That’s the wrong argument. It leads to wrong conclusions about what the problem is and what the fix looks like.
Context For the Writer, Not the Reader
The right argument is narrower and more precise. Upstream documentation context improves what a writer can do. It sharpens judgment. A writer who understands why an API was designed the way it was will make better decisions about what to emphasize, how to frame a concept, which edge cases are worth calling out, and what a confusing behavior actually means for the reader.
That understanding often doesn’t belong in the documentation itself. Often it shouldn’t be there because users don’t need the design history, they need to know how to use the product. What they get, when the writer had the context, is documentation that is clearer and better calibrated to how they’ll actually use it. The understanding shapes the documentation without appearing in it.
The Flagging Function
There’s a second value that’s easy to miss. Upstream context helps writers notice when something is unintuitive or underexplained, and flag it. A writer who knows a particular behavior was a deliberate tradeoff can decide whether that tradeoff is worth surfacing for users.
A writer who doesn’t know it was a tradeoff will document the behavior accurately and may not notice that users are going to find it confusing, because from the outside it just looks like a product decision with no obvious logic.
This is the flagging function: the writer as the first reader who asks “will someone understand this?” It requires understanding the system well enough to recognize when something is missing or non-obvious. Without upstream context, that function is impaired. The writer can describe what exists. They’re less equipped to see what’s unexplained.
Why the staging environment changes the questions you ask
The staging environment contributes to this directly. Using a feature generates questions that a spec doesn’t — questions that come from encountering something unexpected, or something that requires more context than the interface provides. Those are the questions users will have. Bringing them into an SME interview changes the conversation from “explain how this works” to “help me understand why it works the way I just experienced it.”
The questions are sharper because they come from the user’s position, not the document’s.
The cost of the upstream gap is therefore not primarily thin documentation. It’s documentation that is accurate but not well-calibrated. It describes the product correctly but doesn’t consistently anticipate where users will struggle, because the writer didn’t have enough context to see what was non-obvious from the outside.
How to Improve Upstream Knowledge Flow
None of these steps requires a large initiative. They’re changes to when documentation enters the process and what gets passed along when it does.
1. Enter earlier — ideally at the start of Design, not mid-Build.
The earlier a writer enters, the more working documents still exist and the more people who hold the reasoning are still available. A writer involved at the start of Design rather than mid-Build encounters the feature while it’s still being figured out — access to the people debating approaches, the documents capturing constraints, and the reasoning before it disperses.
Why it matters: The archaeology is less extensive because less has been lost yet.
How to frame it: If earlier entry isn’t structurally available, push for it explicitly. Frame it as a handoff quality issue, not a documentation preference.
2. Change what gets handed off — working documents, not just official ones.
Most of what writers need exists somewhere. It’s just not part of what moves. When handing off to documentation, include the working documents alongside the official ones:
- The Confluence page where approaches were debated, not just the requirements doc
- The Notion doc where the feature was scoped, not just the Jira epic
- The earlier draft where alternatives were weighed
These documents aren’t withheld — they’re simply not part of any handoff convention. Making them part of the convention is a small change with a significant impact on what writers can produce.
3. Build capture practices that preserve reasoning before it compresses.
Even with earlier entry and better handoffs, some upstream context will still be generated in conversations and informal channels that don’t survive the stage. Capture practices close that gap:
- Decision logs attached to requirements docs, recording what was decided and why
- Rationale notes — a short paragraph explaining why a design went one way and not another
- Architecture Decision Records (ADRs) extended beyond engineering to product and documentation decisions
These don’t need to be elaborate. A short paragraph is more valuable than nothing, and far more recoverable than a Slack thread that has since disappeared. The Infrastructure section covers how to build and govern these practices at a structural level.
4. Treat the SME interview as clarification, not reconstruction.
When the first three steps are working, the SME interview changes in character:
- Before: Thirty minutes reconstructing decisions from scratch — what the feature does, why it was built that way, what constraints shaped it
- After: Clarifying and refining context you already have — asking about edge cases, confirming reasoning, filling gaps rather than building from nothing
The interview becomes more useful for both the writer and the engineer, and takes less of everyone’s time.
The SME Interview Is a Symptom, Not a Solution
Writers working in organizations with thin upstream flows are not producing thin documentation because they didn’t try hard enough. They’re doing the best possible work with what the system made available, which is usually the conclusions, rarely the reasoning, and almost never the working documents where the reasoning lived.
The SME interview is the most visible symptom of the upstream problem, not the solution to it. It’s a reconstruction effort that produces a compressed version of what should have been available from the start. The interview is useful, necessary in the absence of anything better, and a sign that something earlier in the process didn’t work.
The downstream article examines the other direction: not the knowledge that never reached documentation, but what documentation generates in the world once it ships and why that signal so rarely finds its way back.
Takeaways
- Upstream knowledge loss isn’t a single event. It’s a compression chain that degrades reasoning at every stage of the product development process before writers arrive.
- Writers typically receive official documents — requirements docs, Jira epics, Figma design files — but not the working documents where the reasoning actually lived. The former records conclusions; the latter records why.
- The value of upstream context is writer judgment, not documentation backstory. Understanding why a product works the way it does shapes framing and emphasis decisions, without necessarily appearing in the documentation itself.
- Upstream context also enables the flagging function: a writer who understands the system can recognize when something is unintuitive or underexplained and say so. Without that context, the function is impaired.
- The fix is structural. Earlier entry and better handoff norms — passing working documents alongside official ones — not more SME interviews or more effort by individual writers.