Bridging the Gap: Documenting APIs for Humans and LLMs

Learn how to write documentation that appeals to both Humans and machines

Transcript

2. Twitter: @codejagaban Trust Jamin Okpukoro Dev Advocate @ Uploadcare Bridging the Gap: Documenting APIs for Humans and LLMs
3. What we will cover Step 1.1 - Go Through Description 1. Why this matters now 2. How humans read docs 3. How LLMs consume content 4. Writing for humans 5. Writing for AI 6. What you can do today 7. Measuring success
4. Why this matters now? • ChatGPT currently has 800 million weekly active users • Handles over 1 billion queries every single day • 5 out of every 6 devs uses AI in their workflow (Stack Overflow survey)
6. LLMs now attribute as a top referring source for a lot companies.
8. Your docs are not just for humans anymore — they're training AI that helps humans.
10. How humans read docs 1. Searching for details from Google (SEO) or directly 2. Skimming through your docs 3. Reading from top to bottom 4. Uses navigation 5. Needs: clarity, logical flow, examples and use case, troubleshooting.
11. How LLMs consume content 1. Tokenization (breaking text into chunks) 2. Pattern recognition across content 3. Context building from available text 4. No visual cues or navigation 5. LLMs need: structured data, complete context, clear relationships
12. Step 1.1 - Go Through Description Making docs human-friendly 1. Clear, jargon-free language 2. Logical structure (overview → concepts → reference → tutorials). 3. Working, copy-paste-ready code samples. 4. Error handling and edge cases. 5. Guides: getting started, API reference, integrations, examples, use cases. 6. Well thought out navigation and layout. 7. Search functionality and AI search embedding.
13. Step 1.1 - Go Through Description Making docs AI-friendly: content-wise 1. Chunking: Break content into self-contained sections (300–500 words max). 2. Use OpenAPI specifications for better explanation of API capabilities. 3. Consistent naming and patterns 4. Complete parameter descriptions for all endpoints ❌ Bad: "Use the token from step 2" ✅ Good: "Use your API token (format: sk_live_xxx)"
14. Step 1.1 - Go Through Description Making docs AI-friendly: Structure ✓ Make your docs publicly accessible ✓ Search engine indexed (SEO) ✓ Include markdown export options
15. Step 1.1 - Go Through Description Making docs AI-friendly: Structure ✓ Publicly accessible ✓ Search engine indexed ✓ Include markdown export options ✓ Provide /llms.txt file for AI context ✓ Version your documentation
16. Step 1.1 - Go Through Description Example BEFORE (Human-only): "Configure the webhook as described above" AFTER (Human + AI friendly): "Configure the webhook endpoint: • URL: https://your-domain.com/webhook • Method: POST • Headers: Authorization: Bearer {your_api_key} • Expected response: 200 OK" Complete context in every section.
17. Step 1.1 - Go Through Description 1. Audit 5 key pages for standalone clarity 2. Add OpenAPI spec if you have REST APIs 3. Create /llms.txt with your key documentation URLs 4. Review your most-copied code examples 5. Test: Can someone understand each section independently? Start small, measure impact. Actionable steps you can take this weekend
18. Search engines are being replaced by AI assistants. Your documentation strategy needs to evolve. Optimize for: • Google (traditional search) • ChatGPT, Claude, GitHub Copilot (AI search) • Future AI tools your developers will use. The new Reality: SEO → GEO (Generative Engine Optimization)
19. Step 1.1 - Go Through Description Measuring Success AI Metrics: 1. Accuracy of AI-generated code using your docs. 2. Citation frequency in AI responses. 3. Developer success rate when using AI assistance. Human Metrics: 1. Bounce rate 2. Time on page 3. Time to "wow" factor 4. Dev feedback 5. Support tickets. Set up tracking for both
20. Well written docs, when done right, helps both humans and machines together. Writing for LLMs doesn’t replace writing for humans — it enhances it.
21. Companies already writing for LLMs And you should too
22. MCPs for providing docs context 1. Context7 2. GitMCP 3. VisionCraft MCP
23. Good documentation serves both humans and AI. If an AI can't understand your docs, neither can many of your users. Write once, serve everyone
24. Start with clarity. Everything else follows.
25. Step 1.1 - Go Through Description 1. https://llmstxt.org 2. OpenAPI Docs 3. Vercel Docs 4. Vercel AI adoption 5. Stripe/llms.txt 6. Uploadcare.com/llms.txt Resources
26. THANK YOU! Twitter: @codejagaban