> Markdown version of [/videos/2025-living-documentation-that-can-t-die?t=348](https://www.wearedevelopers.com/videos/2025-living-documentation-that-can-t-die?t=348). Every page supports `.md` or `Accept: text/markdown`. Links point to the HTML versions so they work for humans too. Agent guide: [/agents.md](https://www.wearedevelopers.com/agents.md).

---

# Living Documentation That Can't Die

Stale documentation is actively breaking your AI coding agents by feeding them outdated instructions. Discover how a unified docs-as-code approach transforms passive guidelines into active IDE warnings.

- **Speakers:** [Roman Liukevich](https://www.wearedevelopers.com/@roman-liukevich)
- **Event:** World Congress 2026 Europe - Virtual Stage
- **Published:** July 2, 2026
- **Duration:** 19:16
- **URL:** https://www.wearedevelopers.com/videos/2025-living-documentation-that-can-t-die

## Summary

Software documentation typically dies because knowledge is scattered across external platforms, codebases, and unwritten developer memory. When code and docs live in separate systems, developers become a manual copying bottleneck. The rise of AI coding agents introduces a new danger to this dynamic: while human engineers might recognize and ignore stale documentation, AI agents trust it blindly, confidently generating incorrect code based on outdated instructions.

To prevent documentation rot, engineering teams must unify their context by storing docs in the same repository as their codebase. While a standard documentation folder works, attaching a GitHub Wiki as a Git submodule offers a low-friction alternative. This "docs as code" approach bypasses heavy pull request and CI cycles for minor text updates while allowing live browser edits, ensuring the AI agent sees both the code implementation and the architectural intent simultaneously without slowing down the team.

Once context is unified, agents can automatically generate, synchronize, and validate documentation. However, dumping an entire wiki into an agent’s context wastes tokens and degrades output quality; maintaining a lightweight markdown index file allows the agent to selectively fetch only relevant documents. Furthermore, long architecture guidelines—especially lists exceeding 15 rules—are inevitably ignored by both humans and AI. By feeding these static documents to an agent, teams can automatically convert written principles into deterministic custom lint rules, replacing passive reading with active IDE warnings and transforming developers from manual copying machines into editors of an automated system.

**Keywords:** software documentation strategy, docs as code, ai coding agents, github wiki submodules, documentation synchronization, context token optimization, custom lint rules, stale documentation risks, repository knowledge base, pull request friction, automated code validation, architecture guideline enforcement, markdown index mapping, developer onboarding optimization, ai system prompts

## Chapters

1. **Why scattered knowledge bases lead to stale documentation** (00:17) — Spreading documentation across multiple platforms prevents teams from knowing where the actual source of truth resides.
1. **The persistent gap between AI code agents and documentation** (01:34) — AI assistants integrated into the IDE still lack awareness of external documentation platforms like Confluence or Notion.
1. **Relocating documentation to the main codebase repository** (04:12) — Placing documentation in the same repository as code allows AI agents to read and rely on accurate context.
1. **Evaluating documentation folders versus Git submodules and wikis** (05:48) — Teams must choose between the friction of pull requests in a docs folder or the manual syncing of a separate wiki repository.
1. **Generating and syncing documentation automatically with AI** (10:33) — Configuring AI agents to read and update documentation files during code changes prevents knowledge from falling out of sync.
1. **Managing agent token consumption with an index file** (12:11) — Creating a simple index document helps AI agents selectively read relevant files instead of consuming entire documentation folders.
1. **Validating code style and rules against documentation** (13:12) — Agents can automatically check any code file against documented standards during the review and onboarding processes.
1. **Converting architectural guidelines into custom lint rules** (13:54) — Transforming lengthy lists of architectural rules into hard linting constraints ensures compliance without relying on human memory.
1. **Operating a unified documentation system day to day** (15:46) — Integrating code, documentation, and AI agents into a single automated loop drastically reduces the cost of keeping information current.

## Related Moments

- [The emergent readers of software documentation](https://www.wearedevelopers.com/videos/100284-your-docs-are-now-ai-infrastructure-treat-them-like-it) (from "Your Docs Are Now AI Infrastructure (Treat Them Like It)")
- [Transitioning documentation from human readers to AI agents](https://www.wearedevelopers.com/videos/100199-making-documentation-ai-ready-preparing-your-docs-for-the-llm-era) (from "Making Documentation AI-Ready: Preparing Your Docs for the LLM Era")
- [Assessing the limitations of generating documentation directly from codebases](https://www.wearedevelopers.com/videos/1346-wearedevelopers-live-blockchain-after-the-hype-vibing-all-the-things-big-tech-and-work-best-practices-more) (from "WeAreDevelopers LIVE - Blockchain after the hype, Vibing all the Things, Big Tech and Work Best Practices & more")
- [Adopting documentation-led specification for optimal agent code generation](https://www.wearedevelopers.com/videos/2136-moving-from-playing-with-ai-to-implementing-ai-lee-stott) (from "Moving from Playing with AI to Implementing AI - Lee Stott")
- [Enhancing AI agents with trusted documentation and logical restraints](https://www.wearedevelopers.com/videos/1905-wearedevelopers-live-local-transcriptions-with-open-source-ai) (from "WeAreDevelopers LIVE - Local Transcriptions with Open-Source AI")
- [Orchestrating local developer environments with AI tools](https://www.wearedevelopers.com/videos/1392-mcp-mashups-how-ai-agents-are-reviving-the-programmable-web) (from "MCP Mashups: How AI Agents are Reviving the Programmable Web")

## Related Articles

- [Never delegate the understanding](https://www.wearedevelopers.com/magazine/749-never-delegate-the-understanding)
- [Humanizing Your Documentation](https://www.wearedevelopers.com/magazine/133-humanizing-your-documentation)
- [The real reason we document our code](https://www.wearedevelopers.com/magazine/518-the-real-reason-we-document-our-code)
- [The Web We Broke (And Why AI Agents Are Paying the Price) - AgentCon Berlin](https://www.wearedevelopers.com/magazine/735-the-web-we-broke-and-why-ai-agents-are-paying-the-price-agentcon-berlin)

## Related Jobs

- [Senior AI Agent Software Engineer (Go, Python) (m/f/x)](https://www.wearedevelopers.com/jobs/48277-senior-ai-agent-software-engineer-go-python-m-f-x) at **Dynatrace**
- [Principal Product Manager, Agent Platform](https://www.wearedevelopers.com/jobs/ext/277541-principal-product-manager-agent-platform) at **GitHub**
- [AI Software Engineer (Germany)](https://www.wearedevelopers.com/jobs/48317-ai-software-engineer-germany) at **Sunhat**
- [Staff Software Engineer, Copilot Experiences](https://www.wearedevelopers.com/jobs/ext/164361-staff-software-engineer-copilot-experiences) at **GitHub**
- [Principal Software Engineer, Enterprise AI Platform](https://www.wearedevelopers.com/jobs/ext/1467292-principal-software-engineer-enterprise-ai-platform) at **GitHub**
- [Staff Developer Advocate, GitHub Security Lab](https://www.wearedevelopers.com/jobs/ext/1921051-staff-developer-advocate-github-security-lab) at **GitHub**