AI in docs: Documentation dynamic shift most people seem to ignore
Source: Dev.to
Shift in Documentation Consumers
I’ve worked as a senior technical writer for over 6 years, and I can say with confidence that the consumers of documentation have shifted from human users and developers to AI agents.
Two years ago the big question was “Will AI replace technical writers?” — today it’s not if but when. Companies are already replacing entire technical writing teams with AI‑driven workflows.
When we think about who actually consumes doc content, the answer is increasingly clear: AI models are becoming the primary readers.
Developers now often query their AI coding assistants for details on how to accomplish a specific task. Even after discovering a product, they prefer an easy way for the AI to fetch resources rather than manually searching through the docs.
Impact on Technical Writers
This shift directly affects how we work. Organizations that stay ahead in the AI age are those that optimize their documentation for AI agents. Traditional SEO tactics aren’t enough; AI agents recommend content based on how directly it answers a query.
Key implications
- Docs must be easily discoverable by AI models.
- Content should be concise, structured, and free of unnecessary fluff.
- FAQs become a valuable asset because they map directly to common questions asked of AI agents.
Best Practices for AI‑Friendly Documentation
1. Provide an llms.txt Directive
Add an llms.txt file at the root of your documentation site (e.g., https://yourdocs.com/llms.txt). This file should describe your site’s structure and include links to relevant pages, functioning similarly to a sitemap.xml for search engines.
2. Serve Documentation in Markdown
AI models often prefer .md files because they consume fewer tokens than HTML. Keep a Markdown version of each page and reference it in llms.txt.
3. Ensure Content Negotiation Consistency
When both HTML and Markdown versions exist, make sure the content is identical. Discrepancies can send mixed signals to AI agents.
4. Optimize Content Structure
- Use direct language and avoid filler.
- Incorporate FAQs on every page to address common queries.
- Maintain a clear hierarchy with headings, lists, and code blocks.
5. Build Supporting AI Tools (Optional)
Deploy tools such as an MCP server that hosts your documentation, making it easier for both users and AI agents to locate relevant information.
6. Follow an Agent‑Friendly Specification
Dachary Carey and community contributors maintain an agent‑friendly documentation specification that outlines common patterns AI coding agents use to locate and interpret docs. The AFDocs tool implements this spec and offers a testing environment.
Testing Your Docs with AFDocs
The AFDocs CLI can evaluate how well your documentation conforms to the agent‑friendly specification.
npx afdocs check https://docs.example.com --format scorecardReplace https://docs.example.com with the URL of the site you want to test. The command returns a score and actionable suggestions for improvement.
Moving Forward
Documentation teams should start treating AI agents as the primary audience, especially for developer‑focused docs. When planning information architecture and content structure, keep the recommendations above in mind.
What other tips are you using to build and maintain AI‑friendly documentation? Share your experiences in the comments—let’s learn together how teams are navigating the rise of LLMs.