Documentation is a CI/CD problem

Most developers treat documentation like a chore they can defer until the sprint ends. It’s the same way we used to treat deployments back in 2008.

We used to hand-roll server configurations and FTP files into production. If you forgot a step, the site crashed. Now, we have CI/CD. If your pipeline isn't green, the code doesn't exist.

Your documentation is currently in the 'FTP era.' It’s a collection of stale README.md files, forgotten docs/ folders, and private knowledge living in Slack threads. It is manual, it is inconsistent, and it is almost certainly wrong.

The Drift Problem

The moment you merge a PR that changes a function signature but skip the docstring, your documentation is dead. It’s not just old; it’s worse than nothing. It’s a lie.

We call this documentation drift. In a world of microservices and weekly releases, drift happens in hours, not months.

You change retry_logic_v1 to v2 in config.go, but the internal wiki still tells the platform team to use the old environment variables. That’s a production incident waiting to happen.

Automating this isn't a luxury. It’s the only way to scale an engineering team without drowning in 'How do I run this?' questions.

Code is the Source of Truth

If the information isn't in the code, it's gossip. We've spent a decade convincing ourselves that 'good code is self-documenting.' That was a lie we told to avoid writing docs.

Code tells you how something works. It rarely tells you why or what the side effects are across four other repositories.

We are moving toward a state where the build fails if the documentation doesn't match the implementation. This isn't just checking if a file exists. It’s using LLMs to trace logic from api.py to your public documentation and flagging contradictions.

Imagine a GitHub Action that comments on your PR: 'You changed the rate-limiting logic in middleware/auth.ts, but the /docs/api-limits.md file still says 100 req/sec. Fix it.'

Documentation as a Build Artifact

Stop treating docs as a separate writing project. Treat them as a build artifact.

In the old days, we managed dependencies manually. Now we have package.json and go.mod. Documentation needs the same level of rigor.

At git11, we see teams spending 20% of their velocity just on knowledge transfer. That is a massive tax on innovation.

When we automate the extraction of architecture diagrams and API specs directly from the AST (Abstract Syntax Tree), that tax disappears. Machines are better at tracking cross-file dependencies than you are. Let them do it.

The Death of the Wiki

Internal wikis are where information goes to die. They are disconnected from the git lifecycle.

If I have to leave my IDE and open a browser tab to update a Confluence page, I’m probably not going to do it. And neither are your engineers.

The next evolution moves all of this into the repo. If it’s not in git, it’s not real.

AI-powered tools can now watch your commits and generate the 'human' context. They can see you refactored the database schema in models/user.rb and automatically update the ERD in your technical design doc.

Why LLMs Change the Math

Before 2023, automated docs meant shitty JSDoc outputs that just repeated the function name in a sentence. It was useless noise.

Now, we can feed the entire context of a 50k LOC repository into a model. It understands that ServiceA talks to ServiceB over gRPC and that ServiceB has a cold-start latency issue.

We are building systems that don't just describe code; they explain it. They write the README you were too tired to finish at 6 PM on a Friday.

Stop Writing, Start Auditing

The role of the engineer is shifting from 'writer' to 'editor.' You shouldn't be staring at a blank Markdown file.

You should be reviewing a generated draft that accurately reflects the code you just pushed. You verify the intent, hit approve, and move on to the next ticket.

This is exactly what happened with testing. We stopped manually clicking buttons and started writing scripts to do it. Then we started using tools to generate the test cases.

The New Standard

Within two years, a repo without automated documentation checks will look as unprofessional as a repo without a test suite.

You'll look at a manual README and think: 'How do I know this is actually what the code does?'

The answer will be: you don't.

Don't wait for your team to hit the scale where everything breaks. Start treating your docs like your binaries. Build them, test them, and automate the hell out of them.