AI Lessons Learned for API Documentation Writing

As AI becomes deeply embedded in documentation workflows, API documentation teams are evaluating where it genuinely improves productivity and where human expertise remains indispensable.

In this webinar, Robert Delwood, Lead API Documentation Writer at American Express Global Business Travel, shared practical lessons from his experience using AI across real-world API documentation projects.

A key takeaway from the session was that AI is highly effective at generating first drafts but should not be viewed as a replacement for documentation professionals.

Whether creating OpenAPI specifications, drafting endpoint descriptions, generating code examples, or writing technical articles, AI can significantly reduce the effort required to get started. However, the output still requires careful review, validation, and refinement before it can be trusted by developers.

The discussion highlighted that great API documentation goes beyond documenting fields and endpoints. Developers need context, workflows, business rules, conditional requirements, error-handling guidance, and usage scenarios. While AI can identify and describe what exists in the code, it often misses the nuances that help developers successfully implement and troubleshoot APIs. This is where experienced API writers continue to play a critical role.

Robert also emphasized the importance of verification over automation. AI-generated descriptions, request parameters, response examples, and schemas should always be validated against source code, OpenAPI specifications, and real API behavior. Testing APIs using tools such as Postman remains an essential step in ensuring documentation accurately reflects how the product works. As AI can occasionally hallucinate content or overlook implementation details, the responsibility for documentation accuracy ultimately remains with the writer.

The session explored several high-impact use cases where AI delivers measurable value. These include generating initial OpenAPI specifications from codebases, identifying documentation updates after releases, detecting documentation drift, reviewing documentation quality, and automating repetitive maintenance tasks. For large APIs with hundreds of endpoints and thousands of fields, AI can substantially reduce manual effort while helping teams maintain consistency and coverage.

Another important topic was effective prompting. The quality of AI-generated output depends heavily on the instructions provided. Rather than creating complex prompts immediately, Robert recommended starting with a simple request, reviewing the results, and progressively adding context and requirements until the desired output is achieved. Over time, organizations can build reusable prompt libraries that improve consistency and accelerate documentation workflows.

The webinar concluded with a balanced perspective on the future of AI in documentation. While AI is becoming an indispensable tool for API documentation teams, successful documentation still depends on human judgment, domain expertise, validation, and developer empathy. The role of API writers is evolving from solely creating content to guiding, reviewing, refining, and validating AI-generated outputs.

The future of API documentation is not about AI replacing writers. It’s about skilled documentation professionals using AI to create more accurate, scalable, and developer-focused documentation faster than ever before.

About the Speaker

Robert Delwood is a programmer, writer, and programmer-writer specializing in API documentation. He has nearly two decades of experience creating developer-focused content for APIs, SDKs, and enterprise software. He has held leadership roles at NASA, Microsoft, American Express, and Walmart, where he helped developers successfully adopt complex technologies. Robert believes that great API documentation comes from a combination of high-quality content, a deep understanding of the audience, and the effective use of technology. He has presented at numerous technical conferences, sharing both the principles of excellent API documentation and detailed implementation examples.