Michaela Halliwell (HCSS): Lying to Robots: A Guide to Terrible API Docs (and what to do if you want to fix them)

This talk was presented at the AI The Docs 2025 online conference. We are thrilled to share the recording and the summary with you. 

Visit the talk summary page to see all of the presentations from the conference.

presentation

Michaela Halliwell (Senior Platform Product Manager at HCSS)

Summary

Why is it crucial to treat API documentation as being for machines (LLMs) as well as humans, and what are the limitations of LLMs when interacting with traditional API docs? 

In this presentation, Michaela Halliwell (Senior Platform Product Manager at HCSS) focuses on the best practices for crafting API documentation that is highly compatible with Large Language Models, emphasizing that documentation is now for both humans and machines. 

APIs in the Age of AI Documentation must now serve both human developers and AI systems. LLMs cannot reliably infer context or handle ambiguity, making precise, structured documentation essential. Customer expectations increasingly include AI capabilities alongside APIs, driving the need for machine-consumable content. 

Key Pitfalls and Best Practices 

• Vague or Incomplete Descriptions: Ambiguous fields or notes lead LLMs to “guess.” Best practice: describe every field, constraint, and usage scenario in detail.
• Inconsistent Naming: Variations in naming confuse AI. Best practice: establish and maintain consistent naming conventions.
• Poor or Missing Examples: Inaccurate examples can train LLMs incorrectly. Best practice: provide realistic, schema-aligned request/response examples.
• Human-Centric Writing: Conversational or decorative styles obscure logic. Best practice: use structured headers, explicit authentication flows, and clear rate limit notes readable by both humans and AI.
• Ambiguous Error Handling: Using a single status code for multiple outcomes hides important information. Best practice: treat status codes as contracts, documenting errors, next steps, and retry logic clearly. 

The Evolving Role of Documentation 

• Documentation is increasingly a “live interface” for AI, shaping how LLMs, co-pilots, and agents interact with APIs.
• Protocols like Model Context Protocol (MCP) and agents.json signal a future where APIs actively teach machines how to use them.
• By writing with intention and clarity, technical writers reduce AI guessing, improve reliability, and make complex APIs more accessible to all users. 

Key takeaway: API documentation must be precise, structured, and machine-readable, not just human-friendly, because LLMs and AI agents increasingly rely on docs to interact with APIs. By writing with clarity, consistent naming, complete examples, and explicit error handling, technical writers transform documentation into a “live interface” that reduces AI guessing, ensures reliability, and improves the overall developer experience.