--- title: Delete (most of) your docs | daily.dev description: Relying on markdown docs as the primary source of truth for AI coding tools is an antipattern. When docs and code diverge, AI gets confused by conflicting... canonical: https://daily.dev/posts/delete-most-of-your-docs-gvj33j7ru twitter:card: summary_large_image twitter:site: @dailydotdev og:type: website og:site_name: daily.dev og:title: Delete (most of) your docs | daily.dev og:description: Relying on markdown docs as the primary source of truth for AI coding tools is an antipattern. When docs and code diverge, AI gets confused by conflicting... og:url: https://daily.dev/posts/delete-most-of-your-docs-gvj33j7ru og:image: https://api.daily.dev/og/posts/gvj33j7rU.png og:image:alt: Delete (most of) your docs og:image:width: 1200 og:image:height: 630 og:locale: en --- > ## Documentation Index > Fetch the complete documentation index at: https://daily.dev/llms.txt > Use this file to discover all available pages before exploring further. # Delete (most of) your docs **[Matt Pocock](https://daily.dev/sources/mattpocock)** · 2 min read · 0 upvotes · 0 comments ## Summary Relying on markdown docs as the primary source of truth for AI coding tools is an antipattern. When docs and code diverge, AI gets confused by conflicting signals. Code should be self-explanatory through good structure, formatting, and organization. That said, some docs are genuinely useful: architectural decision records (ADRs) to capture alternatives considered, a domain glossary, and a thin navigation layer. The key distinction is docs that explain what code already shows vs. docs that capture what code cannot express. ## Full article daily.dev links to this article rather than hosting it. Read it at the original source: ## Questions this post answers ### Should I write detailed markdown docs to help AI coding assistants understand my codebase? Extensive markdown documentation as a primary source of truth for AI is discouraged because such docs are not executable or testable against the code, so they drift out of sync over time. When docs and code conflict, an AI assistant cannot tell which one is accurate. Code should instead be self-explanatory through good formatting, file organization, and separation of interfaces from implementations. _Anyone tuning a codebase for AI-assisted development can find related workflow debates on daily.dev._ ### What kind of documentation is still useful when working with AI coding assistants? Three kinds of docs remain valuable: architectural decision records that capture alternatives considered and rejected, a glossary defining domain-specific terms like what an 'order' means in a codebase, and a thin navigational layer that helps AI quickly locate the main parts of the code. None of these should replace the code as the primary source of truth. _Developers refining their AI-assisted coding setup can follow more takes like this on daily.dev._ ## Similar posts on daily.dev - [It's time to move your docs in the repo](https://daily.dev/posts/it-s-time-to-move-your-docs-in-the-repo-5ncacizen) · Hacker News · 1 upvotes · 0 comments - [Documentation is Dead. Long Live Documentation.](https://daily.dev/posts/documentation-is-dead-long-live-documentation--coraeufsl) · DevOps.com · 0 upvotes · 0 comments - [4 Simple Steps to Read Documentation: A Must-Have Skill in the Age of Agentic Coding](https://daily.dev/posts/4-simple-steps-to-read-documentation-a-must-have-skill-in-the-age-of-agentic-coding-jsycqqxne) · Medium · 0 upvotes · 0 comments --- Tags: [#ai-coding](https://daily.dev/tags/ai-coding) [View this post on daily.dev](https://daily.dev/posts/delete-most-of-your-docs-gvj33j7ru) ```json {"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]} {"@context":"https://schema.org","@type":"TechArticle","headline":"Delete (most of) your docs","url":"https://daily.dev/posts/delete-most-of-your-docs-gvj33j7ru","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/delete-most-of-your-docs-gvj33j7ru"},"datePublished":"2026-07-16T08:15:23.503Z","dateModified":"2026-09-13T19:15:09.920Z","description":"Relying on markdown docs as the primary source of truth for AI coding tools is an antipattern. When docs and code diverge, AI gets confused by conflicting...","image":"https://i.ytimg.com/vi/Fj8DKMbdIzU/sddefault.jpg","thumbnailUrl":"https://i.ytimg.com/vi/Fj8DKMbdIzU/sddefault.jpg","isAccessibleForFree":true,"articleSection":"Matt Pocock","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"Matt Pocock","logo":"https://media.daily.dev/image/upload/s--9QIam1r2--/f_auto/v1726499589/logos/mattpocock","url":"https://daily.dev/sources/mattpocock"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/delete-most-of-your-docs-gvj33j7ru","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"ai-coding","timeRequired":"PT2M","video":{"@type":"VideoObject","name":"Delete (most of) your docs","description":"Relying on markdown docs as the primary source of truth for AI coding tools is an antipattern. When docs and code diverge, AI gets confused by conflicting...","thumbnailUrl":"https://i.ytimg.com/vi/Fj8DKMbdIzU/sddefault.jpg","uploadDate":"2026-07-16T08:15:23.503Z","duration":"PT2M","url":"https://api.daily.dev/r/gvj33j7rU","embedUrl":"https://www.youtube.com/embed/Fj8DKMbdIzU"}} {"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"Matt Pocock","item":"https://daily.dev/sources/mattpocock"},{"@type":"ListItem","position":3,"name":"Delete (most of) your docs"}]} {"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/delete-most-of-your-docs-gvj33j7ru#faq","mainEntity":[{"@type":"Question","name":"Should I write detailed markdown docs to help AI coding assistants understand my codebase?","acceptedAnswer":{"@type":"Answer","text":"Extensive markdown documentation as a primary source of truth for AI is discouraged because such docs are not executable or testable against the code, so they drift out of sync over time. When docs and code conflict, an AI assistant cannot tell which one is accurate. Code should instead be self-explanatory through good formatting, file organization, and separation of interfaces from implementations. Anyone tuning a codebase for AI-assisted development can find related workflow debates on daily.dev."}},{"@type":"Question","name":"What kind of documentation is still useful when working with AI coding assistants?","acceptedAnswer":{"@type":"Answer","text":"Three kinds of docs remain valuable: architectural decision records that capture alternatives considered and rejected, a glossary defining domain-specific terms like what an 'order' means in a codebase, and a thin navigational layer that helps AI quickly locate the main parts of the code. None of these should replace the code as the primary source of truth. Developers refining their AI-assisted coding setup can follow more takes like this on daily.dev."}}]} ```