Most teams stopped asking this question years ago. Google Docs won. Non-technical people can’t use git. End of debate.

Except it’s not the end. The reasoning made sense when it was humans doing all the typing, formatting, placing files in folders. That assumption is dissolving faster than most people realize.

I want to examine this question again – not to relitigate old arguments, but because the ground shifted underneath us. We’re going to stress test both approaches. I’ll make the case for repositories, then surface the strongest objections and address them directly.

The answer, IMO, is clear. But there’s something else most teams overlook entirely. And that might matter more than the tooling decision itself.

The Direct Comparison

Someone Leaves the Company

Someone leaves the company. Their name appears on the team page, in project documentation, in onboarding guides – you’re not sure where else. In Google Docs, you start searching. Document by document. Hoping you don’t miss one. Hoping someone else didn’t create a doc you don’t know about.

In a repository with AI as your interface, you say: “This person is no longer working for us. Remove them from the team page, and find any other places in the documentation where they’re mentioned.”

The AI searches. Comes back: “I found five files affected by this. Here are the proposed changes.” You review. You approve. One merge request. Complete coverage. Version history intact.

This is a class of capability Google Docs simply doesn’t have.

What Changed This Month

Here’s another use case, something I use regularly: “What changed in our documentation this month?”

With a repository, the AI reads the commit history and summarizes – by author, by topic, by domain. With Google Docs, you’re clicking through revision histories one document at a time. If you even remember which documents to check.

Quality Automation

And then there’s quality. Documentation I produce through AI doesn’t have typos. Not because I’m careful – because nothing is typed by hand. Quality agents scan the repository continuously. They check for broken links, inconsistent terminology, naming conventions. Standards that humans struggle to maintain consistently become trivial to enforce.

Google Docs has version history. It has comments. It has suggesting mode. For many teams, it’s genuinely sufficient (to write documents.

But it can’t do comprehensive cross-repository updates. It can’t answer “what changed this month” across all your documentation. It can’t enforce quality standards automatically. The repository approach doesn’t just match Google Docs on convenience – it exceeds the capability ceiling.

The AI’s Native Habitat

Another dimension most people miss: When you put documentation in a repository, you’re putting it in the AI’s native habitat.

These tools were trained on code repositories. That’s their breeding ground – where they learned to navigate file structures, parse markdown, understand diffs, follow conventions. When you ask an AI to operate on a repo, you’re asking it to work in the environment it knows best.

You know, your documentation isn’t just for your human team anymore. It’s for your AI team. Every file you structure well, every convention you follow, every piece of context you make explicit – it serves both audiences. The humans who need to understand what’s happening, and the AI agents who need to operate reliably.

Google Docs might be parseable. But the repo is where the AI lives.

Stress Test

I asked Claude to argue against this approach – to surface some objections because I wanted to find the holes I hadn’t articulated yet. The challenges it came back with were reasonable. Here’s how I addressed them.

The objections are reasonable. I don’t think they’t hold.

And there’s a deeper question underneath all of this.

The Dissolution

The distinction between “technical” and “non-technical” people is eroding faster than most realize.

Most teams never considered putting documentation in a git repository because git is for code. Documentation is just something people write into documents – Word, then Google Docs. Different worlds entirely.

There have been attempts to bridge them. Wikis, for example, with Notion being a Google Doc and Wiki blend. But my taste runs toward keeping things as close as you can to the bare metal: text files, version control, minimal abstraction.

The suggestion that docs should live in version-controlled text files, structured like a codebase, surprises most folks. The outdated assumption is that you’d be tied to using command line and type git commands, solve merge conflicts.

No more. AI agents changed the equation. The interface layer shifted.

If you’re not seeing this yet, I am not surprised. It’s kind of hidden still. But, AI can be the documentation interface. Not someday – now. I’m telling you from the trenches: it works.

What does onboarding look like in this model? You teach people the concepts. What is version control? Why does it matter? What’s a commit, a branch, a merge request? You walk them through it once – write some markdown, see what it looks like, understand what a diff shows you.

Then you hand them the AI agent, and probably some dictation tool.

From that point on, they describe what they want in natural language. The AI handles the markdown, the file placement, the structure, the formatting. Contributors don’t need to remember syntax. They need to understand what they’re trying to accomplish.

The barrier that kept documentation in Google Docs – “git is for code, not for us” – is dissolving. If you’re still making decisions based on that assumption, you might be solving a problem that’s disappearing.

Forget Documentation

Really, this is not a tooling question. It is not even about documentation as it has been thought of for the longest time.

It’s a directional choice – about what you’re developing your team, your organization, and yourself toward.

If you solve the “non-technical people can’t use git” problem by adding abstraction layers – a CMS on top, a friendly UI that hides the machinery – you might win convenience. But you also prevent people from developing primitive fluency¹: the intuition for how these building blocks work together and compound into capability over time.

From my point of view, you have to actually buy into this direction. Performatively doing a little bit of AI – “we do use AI, sure. We transcribe meetings” – won’t cut it. That’s not going to put you or your team in step with what’s happening.

I acknowledge it’s difficult to keep up. It really is. However, this is already happening. And unlike betting on future model capabilities, there’s little downside to moving this way. We’re talking about what works right now.

Put yourself and your organization into a state where you’re leveraging what’s already possible – which is in fact a multiplier – and be ready to leverage what’s coming.

Jack Clark in his recent newsletter:

“By the summer I expect that many people who work with frontier AI systems will feel as though they live in a parallel world to people who don’t. And I expect this will be more than just a feeling.”

More on this to come.

The gap that most organizations stumble over isn’t technical per se. It won’t be solved by more capable models, a better UI, or the next release. It’s the same gap that’s plagued knowledge work for decades: work that exists only in people’s heads, processes that depend on the right person being in the room, documentation that’s either outdated or unfindable or both.

Whether the AI models improve next month or next year, the work before us is the same. But there’s some good news.

Last updated: Q3 2019. “We’ll get to it next sprint.”

The Primitives

Nate B. Jones frames it as questions that every workflow needs to answer explicitly:

1. System of record – Where’s the thing we change? What’s the canonical source of truth?
2. State – How do we see that it changed? What’s the before/after?
3. Gate – How do we approve it? What are the defined transitions?
4. Checks – How do we prove it worked? (“It looks good” is not a check.)
5. Rollback – How do we undo it when it doesn’t?
6. Traceability – Who did what, and why?

This framing resonates with my work at TightOps. A decade of work in and with (distributed team) operations, across different companies and cultures, and always finding the same fundamental failure is not the technology. It is a legibility issue – work that isn’t readable, findable, or actionable by anyone who wasn’t in the room when it happened.

James C. Scott developed this into a framework in Seeing Like a State – legibility as what institutions need to function: standardized forms that make complex realities readable and governable. The surname. The cadastral map. The grid city. But that legibility is often crude and extractive, erasing local variation to facilitate state control.

What we are dealing with now is different.

The “magic” of working with AI is that you don’t have to standardize how people work. You can provide the AI with fairly unstructured braindumps, going back and forth between topics, closing some loops and opening others. You can let your conversations be messy. The AI reads through the full transcript and restructures it. It finds the threads, identifies the decisions, surfaces what changed (with some caveats, but that is for another post).

The legibility happens at the output, not the process. People stay human. The AI handles the translation.

Is some nuance lost? Of course. Summarization means emphasis, means choices about what matters. But the cost is negligible, the result is useful, and you end up with a system of record that’s transparent and fair rather than extractive.

Outsource boring work

For years, the answer to all of this was “better documentation.” And for years, the response was a collective shrug. Documentation felt like a technical nice-to-have. So called non-technical people found it even more tedious (good luck getting your sales team to write and maintain documentation). Busy executives had revenue to chase and fires to put out. The cost was upfront – someone has to write it, maintain it, keep it current – and the benefit was abstract, later, somewhere down the line.

So it didn’t happen. Or it happened once, grew stale, and became another artifact nobody trusted.

Two things changed.

First, documentation became more important. It’s no longer just operational hygiene. It is now the key that, excuse my hyperbole, “unlocks an army of agents.” A different vector of scale entirely. The organizations that have their work documented in legible, structured form can tap into capabilities that others simply cannot access. Documentation got promoted from nice-to-have to strategic lever.

Second, the burden shifted. AI can take messy context – a Slack thread, a voice note, a rambling meeting transcript – and turn it into structured, legible documentation. It can figure out where that information belongs in your existing system. It can update what’s already there rather than creating yet another conflicting source.

The skill and discipline that documentation always required? The AI handles that now. You don’t write documentation from scratch – you capture what’s already happening and let AI structure it. What’s left is curation: deciding what matters, what to feed in, what to keep current. A human still steers. But the documentation becomes much more convenient to create and maintain, plus proves its value in such an obvious way every day, that you’ll go there voluntarily.

Compounding

The more you document, the more capable your AI becomes. Not in some abstract “training” sense – you’re not fine-tuning a model. You’re building context.

This is the broader picture: context engineering matters more than prompt engineering. When I tell the AI to process an input and update our team’s documentation accordingly, I don’t fix the prompt when I’m not satisfied with the execution. I fix the context – a readme file, a missing link to a related file, a formatting convention.

The full picture of how your business works, captured in plain text that any AI (or human) can read.

Ask a question about your pricing strategy, and the AI can reference what you’ve already decided. Ask how to solve a problem with your current tool stack, and it knows what tools you’re using. New hires onboard from the same source that agents use. Decisions don’t have to be re-explained every time someone new joins the conversation – human or otherwise.

This is what it means to scale without losing coherence. The documentation isn’t overhead. It’s the substrate.

Entry Point

Pick one workflow, one project, one team. Audit it against the primitives:

• Where’s the system of record? What’s the canonical source of truth?
• Can you see the before/after when something changes?
• What’s the gate? How do changes get approved?
• What checks prove it worked? (Not “it looks good” - something objective.)
• Can you roll back when it doesn’t work?
• Can you trace who did what, and why?

The gaps you find will tell you exactly where the friction lives – why things aren’t shipping, why execution feels harder than it should, why scaling keeps breaking what used to work.

And then: start documenting. Not by writing from scratch, but by capturing what’s already happening and letting AI structure it. Talk. Record. Transcribe. Let the machine make it legible. (I’ll likely publish some templates or guiding ideas for this. But really, the AIs are plenty capable of getting you started. Also: “Can you roll back when it doesn’t work?” Sure you can. You can ask AI to restructure your docs, to replace terminology that you want updated, to break up one file gone too large and unwieldy into smaller ones. Let ‘em work. Review. Approve. Correct direction. It’s inexpensive.)

Bottom line: The primitives that make work agent-legible are the same ones that make work work. Solve for one, you solve for both.

What gives me hope is that the slop isn’t inevitable, and we humans have a pretty reliable history of finding great works (like Shakespeare) out of the sea of slop we ourselves have written. Good stuff rises to the top.

When you build actual systems—when there’s discipline around what gets generated and how it gets checked before it goes out—you can produce work that’s dramatically better than what most humans produce unassisted. I’ve seen marketing copy that people actually click on, emails that get responses, ad creative that outperforms what teams were producing manually. The difference isn’t the model; it’s everything around the model. Retrieval to ground the claims. Validation to catch the errors. Human checkpoints for edge cases. Taste applied at some point in the process.

Is the content information-dense? Is it something you can come back to? Does it respect your time? Those are the right questions, and AI can help you answer them well—if you build the systems to make it happen rather than just connecting a model to a publish button and hoping for the best.

via Nate

By the summer I expect that many people who work with frontier AI systems will feel as though they live in a parallel world to people who don’t. And I expect this will be more than just a feeling

via Jack Clark

Computation is physical

A key problem with ideas, particularly those coming from the Bay Area, is that they often live entirely in the idea space. Most people who think about AGI, superintelligence, scaling laws, and hardware improvements treat these concepts as abstract ideas that can be discussed like philosophical thought experiments. In fact, a lot of the thinking about superintelligence and AGI comes from Oxford-style philosophy. Oxford, the birthplace of effective altruism, mixed with the rationality culture from the Bay Area, gave rise to a strong distortion of how to clearly think about certain ideas. All of this sits on one fundamental misunderstanding of AI and scaling: computation is physical.

via Tim Dettmers

The Wikimedia Foundation says page views have dropped by about eight percent compared to last year. The foundation points to generative AI tools and social networks that display Wikipedia content without sending users to the site. Bots that increasingly resemble real users are also putting more strain on Wikipedia’s infrastructure.

World’s most valuable data. The closest thing to a common, more or less global, understanding we have.

via The Decoder

Early on, while there was less information, experience, even research, it was tough to argue against wild speculations (hype). Times have changed. For those actively using and following the technology, nothing but a moderate view seems at all reasonable.

I still feel like some of the people working at the “labs” are so inundated or immersed, maybe they are truthful but starkly mistaken. They should be smarter than that. The other explanation is that they are bullshitting and lying, misrepresenting.

Hating to be or become more cynical, I’m making a similar error of not following Occam’s razor. Maybe greed is all that’s needed to explain this.

via Anil Dash

via John Gruber

Hence, everything is more or less a regurgitation of a press release. It maybe also be “first impressions”, or some initial test of any thing. There is not much substance. Technical specs, dimensions, version numbers, and similar metrics dominate.

Beyond newsletters though, we have cultivated this race to immediate coverage. However, the cases where this is actually useful are rare. Gossip probably being a more legitimate use case for immediate coverage.

How about some “oldletters“?

They would cover things only after thorough testing, meaning real experience gained by using X over time. A couple of weeks, or a couple of months of usage is what my gut tells me should be about right.

Come to think of it, this category exists, and I have seen it on YouTube with titles such as “6 Months With the …“ (which then is naturally followed by “… – I wasn’t expecting this” 🤦)

I’m more thinking of:

• What happened to X?
• What became of Y?
• X after the dust has settled

Reviews where there is sufficient time in the “Re” to allow for a more balanced perspective and different kinds of insights.

It’s about figuring out what needs to be done, breaking it down into workflows, writing up instructions, and then having somebody else take care of that.

So in essence, it’s just outsourcing, and the same problems that traditionally apply to outsourcing also apply here.

You have the classic problems: dependency, responsibility for the work, potential IP theft, and the need to keep on top of your providers.