You have a Confluence space. It has 847 pages. Nobody reads it.
The getting-started guide is from 2021. The architecture diagram in the "Platform Overview" page still shows the monolith you decomposed two years ago. The payment service docs mention an API key rotation process that references a Jenkins pipeline that no longer exists. And the last person who understood the checkout flow left six months ago.
This is the default state of engineering documentation at companies past Series A. Not because engineers are lazy. Not because nobody cares. But because the tools we've used to document software systems were built for a fundamentally different problem.
The problem isn't documentation culture — it's the medium
Every conversation about bad docs eventually lands on "we need to prioritize documentation" or "engineers should write more." That framing is wrong, and it lets the real culprit off the hook.
Text-based wikis like Confluence and Notion are publishing tools. They're great for writing policies, recording decisions, and storing reference material that doesn't change much. They are catastrophically bad at representing living software systems — systems with dozens of services, hundreds of API endpoints, evolving database schemas, and UI flows that ship every two weeks.
The mismatch is structural, not behavioral. Here's why wikis fail every engineering team, every time.
Failure mode 1: Documentation drift is guaranteed
Software changes faster than any human can update documentation. The moment you write "the OrderService calls the InventoryService to check stock," that statement starts aging. Three sprints later the call goes through an event queue. One sprint after that the InventoryService gets split. The wiki page still says what it said six months ago.
Drift isn't a discipline problem. It's a physics problem. There is no mechanism in a text document that couples its content to the code it describes. The two exist in separate universes and naturally diverge.
The only documentation that doesn't drift is documentation that is either automatically generated from the source of truth (the code, the schema, the spec) or documentation that is so tightly integrated with the development workflow that updating it is part of shipping.
Failure mode 2: Zero discoverability for new engineers
Imagine you join an engineering team on Monday. By Wednesday you need to understand how the checkout flow works. Where do you start?
If you're lucky, someone has written a "Checkout Flow" page. It has a flowchart. The flowchart was made in Lucidchart and is now a static image. There's no drill-down. You can't click on the PaymentService box and see what APIs it exposes. You can't click on the database cylinder and see the schema. You can't click on the UI screen and see which API endpoints it calls.
So you do what every new engineer does: you read code. You spend two weeks reverse-engineering what someone should have been able to show you in twenty minutes.
Text documentation doesn't navigate the way software navigates. Software is a graph of connected systems. Its documentation should be too.
Failure mode 3: No link between the UI and the backend
This one is especially painful in product engineering teams. The frontend team ships a screen. The backend team ships an API. The QA team tests a flow. The documentation team writes a wiki page about the feature. None of these artifacts are connected to each other.
Six months later, someone needs to understand what the "Add to Cart" button actually does. They look at the UI, then they look at the API docs, then they look at the database schema, then they find a Slack thread from a year ago that explains the edge case. The context is scattered across four systems and none of them point to each other.
A system map that shows the UI screen, with clickable points on each interactive element that link to the exact API calls, service dependencies, and database tables — that's not a luxury. That's what documentation should have been all along.
Failure mode 4: Documentation is not a deliverable
In most engineering orgs, the definition of done for a feature is: code merged, tests passing, deployed to production. Documentation is an afterthought that gets scheduled for "next sprint" and then quietly dropped when the next sprint brings new priorities.
The only way to fix this is to make documentation a natural by-product of the development process, not a separate artifact that must be created and maintained. Ideally, the developer should sync service metadata, API specs, and database schemas directly from their repository — with a single command or a CI step — and have that automatically update the visual map.
That's not a workflow that exists in Confluence. It does exist when documentation is treated as code.
What good engineering documentation actually looks like
Here's the mental model that actually works: think about your system the way your product works — as an interactive map.
At the top level, you have a map of your platform: the major features and service domains. Click into a feature, and you see the UI screens that belong to it. Click on a specific region of a screen — say, the payment form — and you see the API endpoints it calls, the services those APIs belong to, the database tables those services write to, and the test cases that cover that path.
Everything is connected. Everything is navigable. And everything is kept in sync not by asking engineers to remember to update a wiki, but by running uigraph sync in CI every time code merges to main.
The core principles of living system documentation
If you're rebuilding your documentation approach from scratch, here's what to optimize for:
-
Visual first, text second. Software systems are graphs. Show them as graphs.
-
Source-linked. Documentation should be generated from or synchronized with actual code artifacts: OpenAPI specs, database schemas, Mermaid diagrams, test suites.
-
Navigable by the product surface. Engineers, PMs, and new hires should be able to start from a UI screen and navigate to the implementation — not start from a list of service names and guess which one is relevant.
-
Updated as part of shipping, not after. The sync should happen in CI. Zero manual steps.
-
Owned by the team, not a documentation team. Every engineer should be able to update the map for their service without learning a specialized tool.
The wiki era of engineering documentation isn't just suboptimal — it's actively counterproductive. It creates a false sense of documentation coverage while the real system knowledge lives in engineers' heads and Slack threads.
The move is to treat your system documentation the same way you treat your system architecture: as something that needs to be designed, structured, versioned, and kept in sync with reality. Visual, interactive, source-linked maps are how you do that.
