18-04-2026
~4 mins read

The space between how we work and how we document

Exploring the gap between business and technical documentation cultures


Because so much of the real work doesn’t happen in systems or tools, but in the gaps between roles, where assumptions collide and understanding is never quite complete.

Lately, one of those gaps has been bothering me. It shows up in something that sounds simple, but isn’t: documentation.


How do we bridge the gap between technical and business documentation? 


On one side, we have developers.
They increasingly embrace docs as code: documentation that is versioned, reviewed, and lives close to the code. It evolves with the system and brings a certain clarity and discipline.

On the other side, we have everyone else: product managers, designers, business stakeholders. Their knowledge lives everywhere: meeting notes, whiteboards, chat threads, and design or analysis tools.


Not because they don’t care, but because their work is fluid, conversational, and fragmented.
And, maybe most importantly: time-constrained.

The hidden cost of "we should document this"

There’s a familiar expectation in many teams: “We should document this properly.”
But “properly” means very different things.

For developers: structured, versioned, reviewed.
For business roles: “We’ve talked this through, it’s on the whiteboard, everyone was aligned. Do we really need to document it again?”

So the gap isn’t just about tools. It’s about different rhythms of work, different definitions of “done”, and different relationships to permanence.


How do you bring people into a documentation culture that requires time they fundamentally don’t have? Or even more directly: Should we expect them to? 


Because asking business roles to adopt docs as code isn’t just a tooling shift.

It's asking them to slow down, structure their thinking differently, and externalize knowledge that currently lives in conversations.


That’s a change in behavior, not just process.

The myth of the single source of truth 

We often talk about a “single source of truth” as if it’s realistic. But in reality, most organizations operate in a multi-source-of-truth ecosystem. 

Maybe the real challenge isn’t consolidating everything into one place, but understanding: 

  • what needs to be durable
  • what can stay
  • and who maintains it.

Can AI help bridge this gap?

AI certainly changes the landscape. It can summarize meetings, extract signals from conversations, generate documentation drafts, or reshape informal input into something structured. For business roles, that sounds like relief: “Maybe I don’t have to document after all.”


A more radical version of this idea is: “Why are we still asking humans to consolidate anything at all?”  Imagine a layer that listens to meetings, tracks conversations across tools, connects signals across roles, and continuously captures what’s happening. Documentation becomes a byproduct of work.


But that raises a more important question:  When does captured information become reliable documentation? 


Because capture is not the same as understanding. We’ve all seen this before: something is discussed, captured somewhere: a whiteboard, a meeting, a thread. And for a moment, it feels like shared understanding. But that feeling doesn’t always last, and it doesn’t always travel.


And if documentation becomes the data layer AI depends on, the bar gets higher, not lower.  AI doesn’t just need more data. It needs trusted, meaningful, well-shaped data.

The work that doesn’t disappear 

Even in a highly automated world, someone still needs to: 

  •  clarify what was actually decided 
  •  distinguish decisions from discussions 
  •  resolve contradictions 
  •  shape something others can rely on.


So the question shifts:  Who ensures that what’s captured actually means something?


Tooling can help.  There are platforms that sit between scattered notes and strict docs-as-code workflows. They lower the barrier.  But they don’t solve the core issue. 
Because the real challenge isn’t:  “Where do I write this down?” 
It’s:  “When and how do I make sense of what just happened?”

So maybe the shift isn’t: “Humans write documentation” → “AI writes documentation”

But:  “Humans curate meaning from what AI captures.”


Which still requires judgment, validation, and intent.


As a “diplomat,” I keep coming back to this: Is the goal to translate between ways of working?
Or to transform them into one?  Translation accepts the gap. Transformation tries to remove it. 

I’m not sure the gap is meant to disappear.

A thought I can’t shake 

What if the problem isn’t that business people don’t document enough, but that our documentation paradigms don’t fit how their knowledge is created?


And I keep coming back to a few questions:

  •  How do we capture knowledge born in conversation without forcing it into unnatural structures? 
  •  Where does documentation need rigor, and where is “good enough” enough? 
  •  What would documentation look like if it truly reflected different ways of working? 
  •  And in an AI-driven world: who ensures that what’s captured actually means something? 


Because maybe this is less about solving a documentation problem, and more about understanding a space we’re still learning how to work in.