--- title: "API quick reference guides" date: 2026-09-27 description: "Introduction Visual shape to an API Example doc scenario: Build an API quick reference The first step: Achieve clarity of..." canonical_url: https://idratherbewriting.com/ai/prompt-eng-api-qrgs --- # API quick reference guides ## Introduction A couple of years ago, we had a problem we were trying to solve with our reference docs. Product teams would meet with users and talk to them about various geo attributes available through our APIs, but the users only had a Javadoc (or similar reference) to navigate. There wasn’t an easy list of attributes to browse, and consequently some users couldn’t find the info they needed and were frustrated. After some trial and error with different approaches, we came up with a solution: comprehensive tree diagrams. Listing hundreds of different elements, the tree diagrams allowed product teams to easily communicate the attributes delivered by the various APIs. Users could go directly to the reference doc source by clicking element links. This solved the findability problem from a usability perspective. However, the diagrams were a pain to maintain, since the APIs kept changing and evolving. Because the diagrams were so popular (both internally and externally), we kept them updated. They became a source of truth for many other documentation questions, even internal questions that we had as technical writers. One engineer even said she used the diagrams to understand one of our more complex API objects (one so complicated, it almost defies human comprehension). As AI tools became more capable, I realized that generating these diagrams wasn’t so hard. AI tools are actually great at creating them, which reduces the effort around both authoring and maintenance. I now have quick reference diagrams for every one of the APIs I support. These QRGs don’t just provide documentation usability; they augment AI chat sessions in helpful ways, especially when you’re constrained by how many tokens you can add into your AI session context. In this article, I’ll walk through the process of using AI to create a quick reference diagram. I’ll share my thought processes behind the approach, how AI tools are used, and other decision-making. I’ll also show how to provide instruction to an agent to build everything in a single instruction. Overall, the QRG as a comprehensive tree diagram provides a number of benefits: - **Enhances API usability for developers.** Developers love quick reference guides, and this gives them an easy way to Ctrl+F to find any element and go directly to it. - **Serves as a concise summary for AI.** The QRG offers a compact representation of the API, useful for priming AI tools or navigating large documentation sets within token limits. ## Visual shape to an API The diagram provides a visual shape to your API, allowing developers to quickly see the primary methods and fields provided. This overcomes the problem of most reference documentation that only communicates information in a series of flat stacked tables. ![In typical reference documentation, objects are deeply nested, but the docs describe the objects in separate tables, without hierarchy. It's hard to visualize the structure and get a clear mental model of the API.](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/tablesinrefdocsnousability.png) Quick reference diagrams represent the hierarchy of your API, with each element linked to its documentation. ![This sample tree diagram visually represents the hierarchical structure of an API, making it easier for developers to understand relationships between objects, methods, and fields at a glance.](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/apiquickrefguidesv2.png) ## Example doc scenario: Build an API quick reference These QRGs are just tree diagrams showing all the elements of the API, with links to each element. However, depending on the size of the API, this could be a formidable task. You might have several hundred elements to show, with a detailed position hierarchy that needs to be accurate. You also need to gather up hundreds of links as well, and somehow test them. There’s a reason this deliverable isn’t usually provided by tech writers: it’s a massive effort to produce and maintain manually — but not so much for AI tools. ## The first step: Achieve clarity of thought The first step in any complex AI-assisted task involves trying to get clarity of thought. Complexity by definition makes it more challenging to have clear paths and thoughts (as there tend to be a lot of unknowns), but it’s important to have a general strategy for tackling complex tasks. Here’s my general strategy: start simple and layer in the complexity. As an analogy, imagine trying to build a skyscraper. You wouldn’t start by building the entire edifice floor by floor, finishing everything as you go. Instead, you would approach it in stages: starting with preparing the foundation, laying the frame and scaffolding, then doing the interior framing, the plumbing, the electrical, the exterior, the windows, and so on. You can approach complex documentation projects in a similar way: proceed in stages through a series of layers, adding in more complexity each time. To do this layered approach, you have to organize the project clearly in your mind first, often with a general outline. Just like writing long-form content, though, the outline might not be the actual path you take through the essay, story, or project. The outline might only provide the starting point, allowing an appropriate jumping off point. You might not know the full complexity from the start. Maybe only the first few steps are visible, and you only have a vague idea of what the future steps might entail. That’s okay. Just keep in mind that AI tools aren’t magic buttons. To avoid unintended outputs, you need to provide clarity about the tasks you want them to accomplish. ## The outline of steps Following this emphasis on clarity of thought, let’s break down the building of our API QRG into an outline of steps. (Since I’ve created about 10 of these tree diagrams already and have been working with them for a while, I already have a good idea of the steps. More realistically, for a complex project we might not have this clear of an idea about the steps.) - **We need a sample tree diagram that can serve as a pattern for the AI to follow.** Tree diagrams could be interpreted in many different ways. The example will make clear to the AI what we mean and want. Fortunately, I already have an example of one of these trees that I can copy. This post, [Task decomposition and complex tree diagrams](/ai/prompt-engineering-task-decomposition.html), has a good example (albeit with fake content). - **Decide on the diagram conventions and notations.** The conventions and notation depend on the language of the API, whether REST, Java, gRPC, or other. Consistency is important, but before the AI starts cranking out hundreds of lines of code, we need to be explicit about how, for example, a method is denoted. How is an object or array represented? Then we need to clarify those conventions below the tree diagram. We can use AI to produce an explicit description of these diagram conventions from an existing tree diagram we like. Then we can use this description for the new AI session to use (essentially reverse engineering the prompt). - **Decide on how to feed the API source into the AI tool.** Will it be better to use the API reference documentation as the source, or the code source files (e.g., proto files, java files) themselves? Many elements in the code source might not be marked as visible in the output (due to various tags or filters that exclude elements from a production build). Additionally, using the code source will probably result in the casing the AI tool uses for each element (`dataSource` or `data_source`). As a result, my preference is to use the generated REST HTML reference documentation, as this will better align with how the same elements are represented in the published documentation. The QRG is meant to reflect the reference documentation, and it’s unclear if the source has structures and conventions that aren’t obvious but which result in a different expression in the generated reference material. - **Gather up the source.** How will we gather up the source files? This somewhat depends on the tool we’re using and the size of the API: *Does the API exceed 1 million tokens?* If so, [Gemini Code Assist](https://codeassist.google/) and the [Gemini web app](https://gemini.google.com/app) might not be candidates. Only [Google AI Studio](https://aistudio.google.com) provides the 2 million token context, but (at the time of this writing) only for the Gemini 1.5 Pro model, which isn’t as good as the Gemini 2.5 Pro model. (For more info about models, see [Gemini models](https://ai.google.dev/gemini-api/docs/models).) - *If the API is less than 1 million tokens, how much less?* We have to leave room for the output tokens as well. If so, we can use the Gemini web app or Gemini Code Assist. Both offer the 2.5 Pro model. - *Should we consolidate all the API files into a single file so that we can easily load it into the AI?* Or is it better to drag over a folder structure, as presumably this folder structure could communicate some metadata about the hierarchy of the content. A script that consolidates the files into a single file could also print the folder hierarchy for each file, providing similar metadata. - *In deciding between the Gemini web app and Gemini Code Assist, which is preferable?* I like the more visual nature of the canvas on the Gemini web app, but Gemini Code Assist makes it easier to load project content. Additionally, the IDE space offers agent workflows, whereas the Gemini app just provides chat. - **Generate a first draft of the diagram output.** Feed the prompt, example, diagram conventions, and reference files into the AI and generate the output. - **Verify the accuracy.** After the AI creates an initial tree diagram, we need to verify that it’s accurate. This will likely involve spot checking the diagram in places. We could also pass the diagram into another AI session and ask the AI to verify its accuracy. We should look at whether the diagram implements the conventions we told it to as well. - **Set up variables.** Because HTML is unwieldy in text diagrams (line breaks would ruin the display), we’ll need to convert each element in the diagram into a variable. Another file will provide the variable definitions that include the HTML link. Each diagram element should be unique, since the same subelement might appear in multiple contexts in an API (for example, `id`). Adopting a variable-naming strategy such as `{{Element_subelement}}` might be best, albeit more confusing. - **Create the variable definitions file.** In my doc system, we can use Jinja conventions and create a variable definitions file, scoped under a namespace to prevent collisions. We’ll keep the namespace short to avoid adding too many tokens to the diagram. - **Embed the diagram.** We’ll need to embed the tree onto a web page that also includes the variable definitions. - **Check the accuracy.** We need to check the accuracy of the links. There could be hundreds of links to click, and the content is access controlled. I have no great strategy for this with ACL’d links other than to do spot checking.