Programmers complain constantly about poor documentation. They struggle to understand legacy systems. They waste hours deciphering code written by others who have since moved on. Yet many of those same developers pour effort into crafting clear explanations when an AI model like Claude sits on the other side of the chat window.
This contradiction jumped out at Mark Dominus. In a post on his long-running blog, the veteran programmer observed a shift in behavior that few had articulated so plainly. The Universe of Discourse laid it out: developers who once resisted writing comments or README files now produce structured prompts and detailed context for large language models. The reason? Immediate payoff.
Feed an AI good documentation and it returns working code, insightful analysis or fixes within seconds. Share the same notes with a human coworker and the response may come days later. Or never. The incentive structure flipped once AI tools entered daily workflows.
But. The pattern reveals something deeper about how teams operate. Documentation has always been a tax on the present for the benefit of the future. Most engineers prioritize shipping features today. Tomorrow’s problems belong to someone else. AI changed the math. It lives in the present. It rewards clarity right now.
Dominus recounted common gripes. “I keep seeing programmers say they can’t get their colleagues to document anything.” Then he noted the exception. When those programmers needed Claude to tackle a thorny problem they invested time. They explained architecture. They listed constraints. They described desired outcomes with precision. The AI delivered. Colleagues often did not.
And this isn’t isolated. Recent discussions across developer forums echo the same observation. A March 2026 post from the Plover blog captured a moment when the industry began to notice its own hypocrisy. Developers treat AI as an eager junior engineer who actually reads the handbook. Human teammates receive terse Slack messages instead.
The consequences stretch beyond annoyance. Poor internal documentation slows onboarding. It increases bugs. It raises maintenance costs. Studies have pegged the drag in the tens of billions annually across the sector. One analysis from ACM’s blog in late 2024 already warned that neglected docs create technical debt that compounds. By 2026 the gap has widened.
Yet tools have evolved. Platforms now generate documentation automatically from code, tickets and comments. FastDoc reported in December 2025 that leading teams shifted from manual authoring to curation. They pull existing artifacts from Jira or GitHub and shape them for different audiences. The bottleneck moved from creation to quality control and relevance.
AI assistance amplifies this. Tools like Mintlify, GitBook and others integrate large language models to suggest updates, fill gaps or even draft entire sections. A March 2026 comparison on GitBook’s blog ranked platforms that blend version control with AI editing. GitBook itself topped the list for technical teams seeking both structure and adaptability.
Still the human element persists. Engineers must decide what matters. They must review AI output. They must maintain standards. Otherwise generated docs become noise. One Qodo.ai post from late 2025 outlined seven practices for code documentation in 2026. Start with purpose and scope. Document invariants. Know the audience. These rules hold whether a person or model writes the first draft.
Companies that treat documentation as strategic win advantages. They retain knowledge when staff leaves. They accelerate new hires. They reduce support tickets. In regulated industries clear records limit legal exposure. The contractor with photos, timestamps and notes prevails in disputes. The one without pays the price. Similar dynamics play out in software.
Recent X conversations reflect growing acceptance. One developer noted AI turns “boring documentation hygiene” into competitive edge for enterprise teams and compliance organizations. Another highlighted how AI converts code into docs, making transparency a feature rather than a chore. The sentiment spreads. Teams experiment with agents that query internal wikis and surface answers instantly.
Yet skepticism remains. AI hallucinates. It invents plausible but incorrect details. Without strong source material those errors propagate. The best results come when humans provide accurate context first. That requires writing it down. For the AI. And, by extension, for the team.
Dominus closed his piece with a touch of wonder. The new world felt obvious in retrospect. Programmers respond to incentives. AI offers fast feedback loops. Humans do not. So behavior changed. The question now is whether organizations will codify the practice. Will they demand the same clarity for human readers that they supply to models?
Some already do. Engineering leaders at forward-looking firms require docs as part of pull requests. They tie promotion to knowledge sharing. They measure the freshness of internal wikis. Others lag. They treat documentation as overhead until a crisis hits. Then they scramble.
The gap between these approaches will determine who thrives. In an era of rapid AI adoption the teams that document well for both silicon and carbon-based colleagues gain speed, resilience and clarity. Those that don’t will spend ever more time asking AI to explain what their predecessors left unsaid.
Progress depends on it. Not because documentation itself is virtuous. But because it works. It always has. Only now the rewards arrive faster. And the audience includes machines that never tire of reading.
WebProNews is an iEntry Publication