Tom Johnson (Google): API quick reference diagrams: boosting comprehension for both human and machine users

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

Tom Johnson (Senior Technical Writer at Google)

Summary 

What new maintenance challenge arose from implementing these comprehensive tree diagrams, especially with frequently changing APIs? 

Tom Johnson (Senior technical writer for Google) presents how AI can improve user comprehension and streamline maintenance of complex API documentation. 

The Challenge with Traditional API References 

Existing Java API reference docs were difficult to navigate, especially for non-engineers. Documentation often consisted of nested tables with objects referencing other objects, resulting in a “giant list of tables” where users lost context. Users wanted a simple, visual, and easy-to-reference overview of hundreds of hierarchical data elements. 

The Solution: Tree Diagrams 

Google developed comprehensive tree diagrams showing all API elements, linked directly to detailed documentation. These diagrams provide a structured, visual overview, allowing users to quickly locate elements and navigate between the diagram and full reference content. The approach proved highly popular and significantly improved usability. 

The Maintenance Challenge 

With complex APIs undergoing frequent updates, manually maintaining diagrams became unsustainable. AI, particularly tools like Gemini, excels at structured, repetitive tasks. It can update specific branches or subbranches, enabling efficient maintenance that would otherwise be impractical. 

AI-Assisted Diagram Creation Pattern 

1. Example Tree: Provide AI with a sample structure to imitate.
2. Define Rules: Establish conventions for representing methods, data types, and responses.
3. Provide Source: Supply reference documentation, addressing token limits and AI input constraints.
4. Generate and Verify: Instruct AI to produce the diagram and validate its accuracy. 

Linking Elements with AI 

After generation, AI links each element to the corresponding section in the reference docs. Clear source links and structured variables help AI automate this complex process efficiently. 

Dual Benefits: Usability and AI Context 

• For Users: The diagrams offer a “one-page visual view” of the API, improving comprehension and element findability.
• For AI: They provide structured context that reduces hallucinations in AI-generated outputs, improving factual accuracy and making the API easier to process in AI sessions. 

Tom Johnson emphasizes that while this approach may not be necessary for all APIs, it offers internal benefits for understanding API structure and provides a foundation for AI-assisted documentation. More implementation details and sample prompts are available on his blog, I’d Rather Be Writing.