Your Best Docs Aren't Written Yet

2026-01-20

How often does your team complain about poor-quality documentation? Internal docs are often in a state of being write-only, out-of-date, unfindable, incomplete or some combination of all of those. That architecture “diagram”? The last one was probably written 3 years ago and no one has a Lucid account anymore.

What’s the real problem?

What to do? First, take a step back. What are folks really complaining about?

Is it about documentation? Or understanding?

When a team highlights poor documentation as a shortcoming, most likely they’re really saying “there’s something here we don’t understand”. Documentation is just a proxy, or a scapegoat perhaps, but not the actual problem. The real problem is that folks don’t know how something works, or more importantly, why it works the way it does.

Just-in-Time Docs

Your code already describes how systems work and interact with each other. In the AI tools era, you can now just ask the IDE “How many of our services subscribe to the “new-customer” SNS topic?” It will just tell you - you don’t need it to be written out in Confluence somewhere.

Does your company have dozens or hundreds of git repos? Just clone them all, and then open the IDE in that uber-directory and keep askign questions.

Higher-Value Docs

Now can you do a couple things:

Delete most of the old what/how docs from your system. The signal-to-noise ratio of your docs will go up by only keeping truly necessary stuff, delegating most of the implementation-y questions to the AI IDE.
Write more important docs about why and for what reason a system exists in the first place. This is far more important than drawing a box with VPCs and load balancers in it. What is the purpose of this system? Why does it use Dynamo instead of a less expensive data store? These are questions that the AI can’t answer, so we really do want to capture this info somewhere.
Do #2 inside each repo. Make a /docs folder at the root, put everything in Markdown, and have it auto publish to your docs product.

Now you have a smaller, more compact permanent library of material and a team focused on answering higher-order questions versus laboriously capturing what the code already tells you.