Your static documentation checker – DEV Community

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:

• Developers underestimate the need for documentation because they think they already understand everything.
• Managers underestimate it because they assume developers can simply read the code and understand the project in a couple of hours.
• Even when people don’t underestimate documentation, they often lack the time and capacity for it. The accurate, up-to-date overview usually sits in the heads of senior developers, who already carry many responsibilities.
• There is no shared culture or intuition about what must be documented and what is obvious. Developers often add comments for trivial functions or describe parameters when clearer variable names or types would have solved the problem. Meanwhile, the truly complex or “hacky” parts remain undocumented.

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.

And yes, with AI we can now ask questions about code directly and often get acceptable answers. However, AI does not reliably provide a correct architectural overview, highlight the genuinely complex parts of the system, or detect factual inconsistencies.

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.

Ducku

Ducku addresses this problem by treating documentation as something that must be monitored continuously, just like code quality or infrastructure drift. It is not a generator or a rewriting tool. It is a static documentation checker that verifies consistency between documentation and the actual system state.

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.

This reduces the cognitive load on developers:

• You no longer need to remember to “update docs later”
• Incomplete documentation no longer accumulates silently
• Outdated or misleading sections are detected early

In other words, Ducku lowers the cost of correctness, not the cost of writing.

Current Capabilities

• Entity presence checking: Detects when environment variables, config keys, ports, API routes, or script names appear in documentation but not in code (and the other way around).
• Parallel entity coverage: Identifies groups of similar items (services, ETL jobs, lambda handlers, CLI commands) and flags undocumented additions.
• Dead module analysis: Detects files that are not imported/used anywhere — either entry points that deserve explanation or obsolete artifacts.
• URL integrity check: Detects broken or outdated links to internal or external resources.
• Spell and style consistency: Basic hygiene that normally gets ignored.

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

What Comes Next

We still have many static check use cases in mind, and they will be also eventually implemented, but after that the next step is helping teams answer 2 questions:

• Is the semantic meaning of things in docs is correct?
• What should be actually documented and what is better left implicit?

The goal is not to force verbose, redundant documentation. Quite the opposite: Ducku will learn patterns of meaningful documentation — the parts where architecture, domain decisions, and operational contracts are encoded — and highlight areas where missing documentation is likely to lead to real onboarding or maintenance cost.

We are starting small — but the direction is:

Documentation consistency as part of CI, not as an afterthought.

If your documentation is not checked, it will rot.

Ducku makes that rot visible.