About the talk 

"A couple of years ago, faced with complaints that users couldn’t find or navigate our reference docs well, I created a comprehensive tree diagram showing all the elements of the API. Using this tree diagram, users could easily use Ctrl+F to locate elements. Additionally, they could click the tree elements to go to the corresponding page in the reference docs. These tree diagrams, which served as a quick reference for the API, became the most popular pages in our API documentation. They solved the findability issues, gave users an easy starting point into the documentation, and communicated the information visually.

However, I also found that these same quick reference diagrams provided an immense boost to AI tools in understanding reference docs. Even for AI tools that support a million tokens of context, a large API reference (with all its HTML tags) can quickly exhaust that limit. The quick reference diagrams compress the entire reference into a much shorter token count. Even if you could upload your entire API reference into an AI tool, the diagram helps the AI become much smarter in interpreting the elements and their relationships with each other.

For technical writers, having this reference content available (both the fully detailed reference and the quick reference diagram, if possible) grounds AI responses with an accurate source of truth. When the AI understands your API reference, you can more easily create documentation related to nearly any aspect of your API. You can also use these quick reference diagrams when tackling extensive cross-documentation projects, such as comparing APIs to each other, creating pathways through your documentation portal, or identifying gaps or inconsistencies across APIs.

As we turn to AI for more advanced documentation authoring, augmenting AI chats with API reference content improves the accuracy of the AI’s responses. Grounding your AI with your API reference basically uploads this intelligence into your AI chat sessions, giving your AI the right knowledge and context to address nearly any documentation scenario. Ultimately, these quick reference diagrams serve a dual role: improving the developer’s understanding of the API while also enhancing the reliability of the AI responses."

About the speaker

Tom Johnson is a senior technical writer for Google in Seattle, Washington. He works on documentation for geo-based APIs integrated as map data into vehicles. Tom writes regularly on the blog idratherbewriting.com, which includes both a course on API documentation and many posts about AI. He likes experimenting with new ideas and techniques as well as reading and engaging with others on topics in the tech comm community.