{"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_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},"jetpack_post_was_ever_published":false},"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":1305,"url":"https:\/\/wade.one\/blog\/2026\/05\/17\/ai-coding-agents-need-better-configuration-not-just-better-models\/","url_meta":{"origin":1245,"position":2},"title":"AI Coding Agents Need Better Configuration, Not Just Better Models","author":"","date":"May 17, 2026","format":false,"excerpt":"The next gains from AI coding agents will come from model improvements and from clearer repo instructions, permissions, tests, and workflows.","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":1304,"url":"https:\/\/wade.one\/blog\/2026\/05\/16\/claude-code-routines-show-where-agent-automation-is-going\/","url_meta":{"origin":1245,"position":3},"title":"Claude Code Routines Show Where Agent Automation Is Going","author":"","date":"May 16, 2026","format":false,"excerpt":"Claude Code's web routines point to a future where coding agents are triggered by events, not only by a developer sitting at a terminal.","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":4},"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":1302,"url":"https:\/\/wade.one\/blog\/2026\/05\/14\/codex-is-moving-into-the-whole-development-workflow\/","url_meta":{"origin":1245,"position":5},"title":"Codex Is Moving Into the Whole Development Workflow","author":"","date":"May 14, 2026","format":false,"excerpt":"OpenAI's latest Codex updates show the category moving beyond chat and autocomplete into review, terminals, browsers, and workflow context.","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}]}}