For the last 15 years I’ve worked on dozens of software projects, and almost every time the documentation was terrible. There are several reasons for this:

Maybe documentation is just obsolete?

only 4% of companies always document their processes, indicating many teams treat documentation as an “optional formality” https://www.bptrends.com/bpt/wp-content/uploads/2015-BPT-Survey-Report.pdf/

At the same time we have strong evidences that without good documentation business just lose huge amount of time-money:

So what is the actual barrier behind such a widespread lack of documentation?

In the brilliant work from Andrew Forward “Software Documentation — Building and Maintaining Artefacts of Communication” have made a good research into the actual reasons.

External Factors Influencing Documentation Quality

As you can see, the lack of time and budget correlates with the frustration that documentation effort may become useless and quickly outdated.
So if we reduce the manual effort and solve the problem of documentation becoming outdated, we can make a significant step forward.

The developer community has already introduced approaches like Javadoc and similar tools that generate documentation automatically from code signatures. This helps, but it covers only a small fraction of what actually needs to be documented.

So we still need well-written, up-to-date, human-readable documentation.

The real challenge is that documentation is not a one-time deliverable but a living artifact. Even if a team writes good docs at the beginning, code evolves faster than documentation habits. Without continuous synchronization, documentation becomes misleading — which is even worse than having none.

This means the bottleneck is not writing documentation, but keeping it correct.

Solutions

AI

AI is actually good at matching simple patterns between code and docs. There are some nice solutions where you can automate documentation drift via AI:

This approach works well for:

However, AI has clear limitations:

In other words, AI can help rewrite and improve text, but it is not yet reliable as a source of truth validator.

Static checks

Tools like Ducku addresses this problem by treating documentation as something that must be monitored continuously, just like code quality or infrastructure drift. It works purely algorythmically so not affected by hallucinations, although false positives are of course still possible. But since it’s configurable, you can mute certain use cases.

Ducku works by extracting structural signals from your repository — environment variables, API routes, service entry points, module imports, directory structure, configuration keys — and comparing them with what is referenced in your READMEs and wiki. When something diverges, it flags it.

Current Capabilities

This is already enough to reduce a large portion of silent documentation drift in real projects.

Conclusion

Documentation does not fail because engineers are careless. It fails because there is no feedback loop that keeps it aligned with the system it describes. Code has tests. Infrastructure has drift detection. CI has policy gates. Documentation, in most teams, has nothing.

AI can improve phrasing and restore context, but it cannot reliably tell whether documentation is correct. Static checks, on the other hand, can validate factual alignment, but they cannot explain intent or domain logic.

Both together they can bring what you need.