{"id":1245,"date":"2026-04-30T18:00:00","date_gmt":"2026-04-30T17:00:00","guid":{"rendered":"https:\/\/wade.one\/blog\/?p=1245"},"modified":"2026-04-23T23:51:16","modified_gmt":"2026-04-23T23:51:16","slug":"documentation-now-needs-to-work-for-ai-agents-too","status":"publish","type":"post","link":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/","title":{"rendered":"Documentation Now Needs to Work for AI Agents Too"},"content":{"rendered":"

\"A<\/p>\n

Documentation now needs to work for AI agents too. That does not mean writing docs for robots and forgetting humans. It means accepting that AI coding tools are now a real consumer of developer documentation, and they fail in predictable ways when the documentation is messy, stale, or hard to retrieve.<\/p>\n

Vercel published a useful guide on this recently<\/a>, and the short version feels right: agents do not need animated code blocks, heavy navigation, or a pile of HTML. They need clean retrieval, discoverable structure, freshness metadata, canonical URLs, and tool access where precision matters.<\/p>\n

Bad docs have always been expensive. They waste human time, cause wrong assumptions, and slow onboarding. Now they also make AI tools worse. If an agent pulls stale examples, misses the version number, or cannot tell which page is canonical, it will produce worse code and a developer will still have to clean up the confusion.<\/p>\n

The practical work is not glamorous: clean markdown, useful indexes like llms.txt<\/code> or sitemap.md<\/code>, clear last-updated dates, project-specific instructions near the code, and search or MCP tools where the docs need to be queried carefully. But this is exactly the sort of boring work that makes AI-assisted development less annoying. Better context is now part of the engineering system.<\/p>\n","protected":false},"excerpt":{"rendered":"

Developer documentation is becoming an interface for AI agents as well as humans. That means clean markdown, metadata, and tool access matter more.<\/p>\n","protected":false},"author":0,"featured_media":0,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":"","jetpack_publicize_message":"","jetpack_publicize_feature_enabled":true,"jetpack_social_post_already_shared":true,"jetpack_social_options":{"image_generator_settings":{"template":"highway","default_image_id":0,"font":"","enabled":false},"version":2}},"categories":[26,25],"tags":[123,67,69,125],"class_list":["post-1245","post","type-post","status-publish","format-standard","hentry","category-ai","category-software-engineer","tag-ai-agents","tag-developer-experience","tag-documentation","tag-llms-txt"],"yoast_head":"\nDocumentation Now Needs to Work for AI Agents Too - wade.one<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/\" \/>\n<meta property=\"og:locale\" content=\"en_GB\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Documentation Now Needs to Work for AI Agents Too - wade.one\" \/>\n<meta property=\"og:description\" content=\"Developer documentation is becoming an interface for AI agents as well as humans. That means clean markdown, metadata, and tool access matter more.\" \/>\n<meta property=\"og:url\" content=\"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/\" \/>\n<meta property=\"og:site_name\" content=\"wade.one\" \/>\n<meta property=\"article:published_time\" content=\"2026-04-30T17:00:00+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/wade.one\/blog\/wp-content\/uploads\/2026\/04\/01-technical-manual.jpg\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@wadewomersley\" \/>\n<meta name=\"twitter:site\" content=\"@wadewomersley\" \/>\n<meta name=\"twitter:label1\" content=\"Estimated reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"1 minute\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\\\/\\\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/#article\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/\"},\"author\":{\"name\":\"\",\"@id\":\"\"},\"headline\":\"Documentation Now Needs to Work for AI Agents Too\",\"datePublished\":\"2026-04-30T17:00:00+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/\"},\"wordCount\":217,\"publisher\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#\\\/schema\\\/person\\\/8b4739f8f8bb2cff5d792d4b8779fcc3\"},\"image\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/04\\\/01-technical-manual.jpg\",\"keywords\":[\"ai-agents\",\"developer-experience\",\"documentation\",\"llms-txt\"],\"articleSection\":[\"AI\",\"Software Engineer\"],\"inLanguage\":\"en-GB\"},{\"@type\":\"WebPage\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/\",\"url\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/\",\"name\":\"Documentation Now Needs to Work for AI Agents Too - wade.one\",\"isPartOf\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/#primaryimage\"},\"image\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/#primaryimage\"},\"thumbnailUrl\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/04\\\/01-technical-manual.jpg\",\"datePublished\":\"2026-04-30T17:00:00+00:00\",\"breadcrumb\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/#breadcrumb\"},\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/#primaryimage\",\"url\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/04\\\/01-technical-manual.jpg\",\"contentUrl\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2026\\\/04\\\/01-technical-manual.jpg\",\"width\":1024,\"height\":768,\"caption\":\"A technical manual for an early digital trainer\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/2026\\\/04\\\/30\\\/documentation-now-needs-to-work-for-ai-agents-too\\\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\\\/\\\/wade.one\\\/blog\\\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Documentation Now Needs to Work for AI Agents Too\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#website\",\"url\":\"https:\\\/\\\/wade.one\\\/blog\\\/\",\"name\":\"wade.one\",\"description\":\"wade womersley - york based software engineer\",\"publisher\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#\\\/schema\\\/person\\\/8b4739f8f8bb2cff5d792d4b8779fcc3\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\\\/\\\/wade.one\\\/blog\\\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-GB\"},{\"@type\":[\"Person\",\"Organization\"],\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/#\\\/schema\\\/person\\\/8b4739f8f8bb2cff5d792d4b8779fcc3\",\"name\":\"Wade Womersley\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\",\"url\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\",\"contentUrl\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\",\"width\":202,\"height\":200,\"caption\":\"Wade Womersley\"},\"logo\":{\"@id\":\"https:\\\/\\\/wade.one\\\/blog\\\/wp-content\\\/uploads\\\/2015\\\/02\\\/200px.png\"}}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Documentation Now Needs to Work for AI Agents Too - wade.one","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/","og_locale":"en_GB","og_type":"article","og_title":"Documentation Now Needs to Work for AI Agents Too - wade.one","og_description":"Developer documentation is becoming an interface for AI agents as well as humans. That means clean markdown, metadata, and tool access matter more.","og_url":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/","og_site_name":"wade.one","article_published_time":"2026-04-30T17:00:00+00:00","og_image":[{"url":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2026\/04\/01-technical-manual.jpg","type":"","width":"","height":""}],"twitter_card":"summary_large_image","twitter_creator":"@wadewomersley","twitter_site":"@wadewomersley","twitter_misc":{"Estimated reading time":"1 minute"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/#article","isPartOf":{"@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/"},"author":{"name":"","@id":""},"headline":"Documentation Now Needs to Work for AI Agents Too","datePublished":"2026-04-30T17:00:00+00:00","mainEntityOfPage":{"@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/"},"wordCount":217,"publisher":{"@id":"https:\/\/wade.one\/blog\/#\/schema\/person\/8b4739f8f8bb2cff5d792d4b8779fcc3"},"image":{"@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/#primaryimage"},"thumbnailUrl":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2026\/04\/01-technical-manual.jpg","keywords":["ai-agents","developer-experience","documentation","llms-txt"],"articleSection":["AI","Software Engineer"],"inLanguage":"en-GB"},{"@type":"WebPage","@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/","url":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/","name":"Documentation Now Needs to Work for AI Agents Too - wade.one","isPartOf":{"@id":"https:\/\/wade.one\/blog\/#website"},"primaryImageOfPage":{"@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/#primaryimage"},"image":{"@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/#primaryimage"},"thumbnailUrl":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2026\/04\/01-technical-manual.jpg","datePublished":"2026-04-30T17:00:00+00:00","breadcrumb":{"@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/#breadcrumb"},"inLanguage":"en-GB","potentialAction":[{"@type":"ReadAction","target":["https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/"]}]},{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/#primaryimage","url":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2026\/04\/01-technical-manual.jpg","contentUrl":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2026\/04\/01-technical-manual.jpg","width":1024,"height":768,"caption":"A technical manual for an early digital trainer"},{"@type":"BreadcrumbList","@id":"https:\/\/wade.one\/blog\/2026\/04\/30\/documentation-now-needs-to-work-for-ai-agents-too\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/wade.one\/blog\/"},{"@type":"ListItem","position":2,"name":"Documentation Now Needs to Work for AI Agents Too"}]},{"@type":"WebSite","@id":"https:\/\/wade.one\/blog\/#website","url":"https:\/\/wade.one\/blog\/","name":"wade.one","description":"wade womersley - york based software engineer","publisher":{"@id":"https:\/\/wade.one\/blog\/#\/schema\/person\/8b4739f8f8bb2cff5d792d4b8779fcc3"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/wade.one\/blog\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-GB"},{"@type":["Person","Organization"],"@id":"https:\/\/wade.one\/blog\/#\/schema\/person\/8b4739f8f8bb2cff5d792d4b8779fcc3","name":"Wade Womersley","image":{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png","url":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png","contentUrl":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png","width":202,"height":200,"caption":"Wade Womersley"},"logo":{"@id":"https:\/\/wade.one\/blog\/wp-content\/uploads\/2015\/02\/200px.png"}}]}},"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack-related-posts":[{"id":1243,"url":"https:\/\/wade.one\/blog\/2026\/04\/29\/next-js-is-starting-to-treat-ai-agents-as-real-users\/","url_meta":{"origin":1245,"position":0},"title":"Next.js Is Starting to Treat AI Agents as Real Users","author":"","date":"April 29, 2026","format":false,"excerpt":"Next.js is starting to treat AI agents as real users of the framework. That is more important than it first sounds.","rel":"","context":"In "AI"","block_context":{"text":"AI","link":"https:\/\/wade.one\/blog\/category\/ai\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1233,"url":"https:\/\/wade.one\/blog\/2026\/04\/24\/ai-coding-agents-are-becoming-normal-developer-infrastructure\/","url_meta":{"origin":1245,"position":1},"title":"AI Coding Agents Are Becoming Normal Developer Infrastructure","author":"","date":"April 24, 2026","format":false,"excerpt":"AI coding agents are moving from novelty demos into normal developer infrastructure. The useful question now is how teams manage them properly.","rel":"","context":"In "AI"","block_context":{"text":"AI","link":"https:\/\/wade.one\/blog\/category\/ai\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1239,"url":"https:\/\/wade.one\/blog\/2026\/04\/27\/copilot-autopilot-sounds-useful-but-guardrails-matter\/","url_meta":{"origin":1245,"position":2},"title":"Copilot Autopilot Sounds Useful, but Guardrails Matter","author":"","date":"April 27, 2026","format":false,"excerpt":"Autonomous coding sessions can be useful, but only when teams are clear about permissions, tests, and what still needs a human decision.","rel":"","context":"In "AI"","block_context":{"text":"AI","link":"https:\/\/wade.one\/blog\/category\/ai\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1235,"url":"https:\/\/wade.one\/blog\/2026\/04\/25\/codex-moving-beyond-code-is-the-interesting-part\/","url_meta":{"origin":1245,"position":3},"title":"Codex Moving Beyond Code Is the Interesting Part","author":"","date":"April 25, 2026","format":false,"excerpt":"Codex moving beyond code is more interesting than another model benchmark. The harder problem is where the agent sits in the actual workflow.","rel":"","context":"In "AI"","block_context":{"text":"AI","link":"https:\/\/wade.one\/blog\/category\/ai\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1237,"url":"https:\/\/wade.one\/blog\/2026\/04\/26\/ai-code-review-should-reduce-noise-not-add-more-comments\/","url_meta":{"origin":1245,"position":4},"title":"AI Code Review Should Reduce Noise, Not Add More Comments","author":"","date":"April 26, 2026","format":false,"excerpt":"The best use of AI in code review is not adding more comments. It is finding the few things that actually matter.","rel":"","context":"In "AI"","block_context":{"text":"AI","link":"https:\/\/wade.one\/blog\/category\/ai\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]},{"id":1155,"url":"https:\/\/wade.one\/blog\/2026\/03\/26\/ai-is-not-a-bubble-denial-is-the-real-problem\/","url_meta":{"origin":1245,"position":5},"title":"AI Is Not a Bubble. Denial Is the Real Problem","author":"","date":"March 26, 2026","format":false,"excerpt":"AI tooling is not going away. What a lot of people are calling a bubble looks more like denial in the face of tools that are already becoming normal developer infrastructure.","rel":"","context":"In "AI"","block_context":{"text":"AI","link":"https:\/\/wade.one\/blog\/category\/ai\/"},"img":{"alt_text":"","src":"","width":0,"height":0},"classes":[]}],"_links":{"self":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts\/1245","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/types\/post"}],"replies":[{"embeddable":true,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/comments?post=1245"}],"version-history":[{"count":1,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts\/1245\/revisions"}],"predecessor-version":[{"id":1279,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/posts\/1245\/revisions\/1279"}],"wp:attachment":[{"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/media?parent=1245"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/categories?post=1245"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/wade.one\/blog\/wp-json\/wp\/v2\/tags?post=1245"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}