Skip to content
boringdocs
Back to Blog

Your Documentation Is a Dependency Graph. Act Like It.

Documentation isn't a collection of files. It's a dependency graph. When one node changes, the ripples propagate silently. Here's why most teams can't see the breakage — and what to do about it.

• boringdocs
documentation dependency graph doc-code sync API documentation AI agents technical writing developer experience

Your Documentation Is a Dependency Graph. Act Like It.

Your codebase has a dependency graph. You know this. You’ve seen it in your package manager, your build tool, your CI pipeline. When package A depends on package B, and B changes, A breaks. You have tooling for this. Lock files. Semantic versioning. Automated tests.

Your documentation has a dependency graph too. Nobody talks about it. Nobody tools for it. And it’s breaking silently every day.

The Graph You Can’t See

Here’s what the documentation dependency graph looks like for a typical API product:

Code (endpoints, schemas, error codes)
  └── API Reference (describes the code)
        ├── Getting Started Guide (references the API reference)
        ├── Integration Tutorials (depend on the getting started guide)
        ├── SDK Documentation (wraps the API reference)
        ├── Changelog (describes changes to the code)
        └── MCP Server (serves the API reference to AI agents)
              └── AI-Generated Code (produced by agents reading MCP)

That’s not a list of documents. That’s a dependency graph. Each node depends on the nodes above it. When a node changes, everything below it is potentially invalidated.

When you rename a parameter in your code, you don’t just break the API reference. You break the getting-started guide that shows the old parameter name. You break the tutorial that copies it. You break the SDK docs that reference it. You break the MCP server that serves it. And you break every piece of AI-generated code that was produced from the old documentation.

One change. Six downstream breakages. Most of them invisible.

Why Code Has This Solved (And Docs Don’t)

Code dependency graphs are solved because they’re machine-readable. Your package manager can parse package.json. Your build tool can trace imports. Your CI can run tests against the dependency tree. When something breaks, you get a red build.

Documentation dependency graphs are not machine-readable. They’re implicit. The link between your API reference and your getting-started guide is a Markdown file that mentions an endpoint name. The link between your MCP server and your API reference is a configuration file that points to a URL. The link between an AI agent’s output and your documentation is a context window that nobody logs.

You can’t test what you can’t see. And you can’t see a dependency graph that exists only as implicit references between text files.

The Compounding Problem

Here’s what makes this worse: documentation dependency graphs are deeper than code dependency graphs.

In code, dependencies are usually one or two levels deep. Your app depends on a library. The library depends on another library. Three levels, maybe four.

In documentation, the chains are longer. Code → API reference → Tutorial → Video walkthrough → Community blog post → Stack Overflow answer. Six levels of dependency, and your team only controls the first two.

When you change an error code in your API, the Stack Overflow answer from 2024 that shows the old error code is now wrong. You’ll never know. But the developer who finds it via Google will. And the AI agent that ingests it via an MCP server will.

The AI Agent Multiplier

AI agents make the documentation dependency graph problem worse in two specific ways.

First, they’re leaf nodes that nobody tracks. When Claude Code generates integration code based on your docs, that code becomes a consumer of your documentation dependency graph. If your docs were wrong, the generated code is wrong. That code gets committed, shipped, and becomes part of someone else’s dependency graph. Your documentation error has now propagated into another codebase.

Second, they shorten the feedback loop for breakage. In the old world, a documentation error might take weeks to surface — a developer hits a wrong example, files a ticket, someone investigates. In the AI agent world, the error surfaces in seconds. The agent reads your docs, generates wrong code, and the developer runs it. The feedback loop went from weeks to seconds. But the detection loop is still weeks. The developer doesn’t know the code failed because the docs were wrong. They think they made a mistake.

What Dependency-Aware Documentation Looks Like

The fix isn’t to document more carefully. The fix is to make the dependency graph visible and testable.

1. Map the graph explicitly.

For each piece of documentation, ask: what does this depend on? What depends on this? A simple spreadsheet works as a starting point. For each doc page, list:

  • Upstream dependencies (what code, what other docs)
  • Downstream consumers (what tutorials, what MCP servers, what SDKs)

You don’t need a tool for this. You need a conversation. Once you see the graph, you’ll start making different decisions.

2. Test the critical paths.

You can’t test every dependency. But you can test the critical ones. The API reference is the root node of most documentation dependency graphs. If the API reference is accurate, the rest of the graph has a chance. If it’s wrong, everything downstream is compromised.

This is the boringdocs thesis: validate the root node continuously. When the API reference is accurate, you protect the entire graph.

3. Version your docs with your code.

Code has semantic versioning. Documentation should too — and it should be tied to the code version, not the docs version. When you ship v2.1 of your API, the docs for v2.1 should be shipped in the same commit. Not in a separate PR. Not in a separate repo. The same commit.

This makes the dependency graph versionable. You can trace which version of the docs corresponds to which version of the code. When someone reports a doc error, you can check: are they reading the right version?

4. Alert on upstream changes.

When code changes, the docs that depend on that code should be flagged. Not as a suggestion. As a build warning. “You changed the limit parameter to page_size in endpoints/users.py. The following 4 doc files reference limit:”

This is what it means to treat documentation as a dependency graph. Upstream changes trigger downstream alerts. Just like a broken test in your CI pipeline.

The Graph Is Already There

Here’s the thing: the dependency graph already exists. Every time you write a tutorial that references an API endpoint, you’re creating a dependency edge. Every time you configure an MCP server to serve your docs, you’re adding a consumer. Every time an AI agent reads your documentation and generates code, you’re adding a leaf node.

The graph is there. It’s just invisible.

Making it visible — mapping the dependencies, testing the critical paths, versioning with code, alerting on upstream changes — is what it means to treat documentation as infrastructure. Not as content. Not as an afterthought. As a dependency graph that deserves the same treatment you give your code.

Your documentation has a dependency graph. boringdocs makes it testable. Join the waitlist — the validation layer that checks the root node so the rest of the graph has a chance.