Although I don’t work in road ecology or traffic engineering, the author somehow pulled me through 300 pages on this topic. He managed this not just through vivid language and diction, but by personally visiting places and telling stories about the specific challenges that animals, “carers,” forest service workers, and others faced as freeways and highways bisected and dissected their environments.
To use an analogy, suppose you’re a barista making espresso coffee. An AGI-capable robot trained as a barista is able to make all the coffee that a regular barista can make but twice as fast. Further, the Android barista can create exquisite espresso art in any shape that humans request, wowing them and making the experience novel. Soon the human barista is replaced. After all, the paying customer would rather pay $2.50 for a robot to make a latte instead of $5.00, especially when it tastes the same.
Most code samples in documentation are fairly basic, which is by design. Documentation tries to show the most common use of the API, not advanced scenarios for an enterprise-grade app whose complexity would easily overwhelm developers. (At that point, you end up with a sample app.)
With AI tools built directly into your authoring tool or IDE (such as VS Code), fixing simple doc bugs can become a mechanical, click-button task. Here’s the approach to fixing simple doc bugs:
(Note: The fact that I’m writing a book review on this topic might seem odd given that I usually focus on tech comm topics. However, I document APIs for getting map data into cars, so I sometimes read books related to the automotive and transportation domain. I also run a book club at work focused on these books.)
During the past few weeks, I’ve felt like my brain’s RPMs have been in the red zone. Granted, the constant stream of chaotic political news hasn’t helped—but regardless of current political events, I’m frequently checking the news, my email, and chat messages and operating in a mode that isn’t great. Reading long-form books has proven to be difficult. I run a book club at work focused on automotive and transportation books, and it took me two months to make it through a single book (granted, it was a 300-page historically dense book, but still).
“Biohacking” might be a pretentious cyber term for what is otherwise a straightforward experiment. For 10 days, I tracked my food and exercise levels while also wearing a continuous glucose monitor (CGM) to track my glucose levels. I then used AI to pair up the food + exercise with the glucose readings and perform an analysis about triggers for glucose spikes and recommendations to avoid them.
I want you to act as my AI stream journal (similar to a bullet journal), for the day. In this chat session, I’ll log 3 kinds of notes: tasks, thoughts, and events. Tasks are to-do list items. Thoughts are random ideas or notes I have. Events consist of food eaten, exercise, or descriptions of my internal states. The point is to have an easy way to dump all the scattered information in my head into a central log that you organize and analyze on my behalf.
Here’s an example of a resource description from the Mailchimp API’s Campaigns resource:
Typically, an API will have a number of endpoints grouped under the same resource. In this case, you describe both the general resource and the individual endpoints. For example, the Campaigns resource has various endpoints that are also described:
POST /campaigns
GET /campaigns
GET /campaigns/{campaign_id}
PATCH /campaigns/{campaign_id}
DELETE /campaigns/{campaign_id}
POST /campaigns/{campaign_id}/actions/cancel-send
POST /campaigns/{campaign_id}/actions/pause
POST /campaigns/{campaign_id}/actions/replicate
POST /campaigns/{campaign_id}/actions/resume
POST /campaigns/{campaign_id}/actions/schedule
POST /campaigns/{campaign_id}/actions/send
POST /campaigns/{campaign_id}/actions/test
POST /campaigns/{campaign_id}/actions/unschedule
Here’s a resource description for the Membership resource in the Box API:
For the Membership resource (or “object,” as they call it), there are 7 different endpoints or methods you can call. The Box API describes the Membership resource and each of the endpoints that lets you access the resource.
Sometimes the general resource isn’t described; instead, it just groups the endpoints. The bulk of the description appears in each endpoint. For example, in the Eventbrite API, here’s the Events resource:
Although the Events resource isn’t described here, descriptions are added for each of the Events endpoints. The Events resource contains all of these endpoints:
/events/search/
/events/
/events/:id/
/events/:id/
/events/:id/publish/
/events/:id/cancel/
/events/:id/
/events/:id/display_settings/
/events/:id/display_settings/
/events/:id/ticket_classes/
/events/:id/ticket_classes/:ticket_class_id/
/events/:id/canned_questions/
/events/:id/questions/
/events/:id/attendees/
/events/:id/discounts
And so on.
When developers create APIs, they have a design question to consider: Use many variants of endpoints (as with Eventbrite’s API), or provide lots of parameters to configure the same endpoint. Often there’s a balance between the two. The trend seems to be toward providing separate endpoints rather than supplying a host of potentially confusing parameters within the same endpoint. On the other hand, GraphQL APIs (which I don’t cover in this course) provide one endpoint with different ways to query the information the endpoint contains. See GraphQL And REST Differences Explained With Burgers for a good explanation about GraphQL versus REST.
As another example, the previous version of the Instagram API depicted a Relationships resource as follows:
The Relationships resource isn’t described but rather acts as a container for relationship endpoints. Descriptions are added for each of the resources grouped within the Relationships resource:
For another example of an API with resources and endpoints, check out the Trello API.
The description of the resource is likely something you’ll re-use in different places — product overviews, tutorials, code samples, quick references, etc. As a result, put a lot of effort into crafting it. Consider storing the description in a re-usable snippet in your authoring tool so that you can list it without resorting to copy/paste methods in your quick start guide.
Terminology for describing the resource
The exact terminology for referring to resources varies. The “things” that you access using a URL can be referred to in a variety of ways, but “resource” is the most common term because you access them through a URL, or uniform resource locator. Other than “resources,” you might see terms such as API calls, endpoints, API methods, calls, objects, services, and requests. Some docs get around the situation by not calling them anything explicitly except “Reference.”
Despite the variety with terminology, generally an API has various “resources” that you access through “endpoints.” The endpoints give you access to the resource. (But terminology isn’t standard, so expect variety.)
Recognize the difference between reference docs versus user guides
Resource descriptions (as well as endpoint descriptions) are typically short, usually 1-3 sentences. What if you have a lot more detail to add? In these situations, keep in mind the difference between reference documentation and user guides/tutorials:
Reference documentation: Concise, bare-bones information that developers can quickly reference.
User guides/tutorials: More elaborate detail about how to use the API, including step-by-step instructions, code samples, concepts, and procedures. I go into much more detail about this content in Documenting concepts sections.
Although the description in an API reference topic provides a 1-3 sentence summary of the information that the resource contains, you might expand on this with much greater detail in the user guide. (You could link the reference description to the places in the guide where you provide more detail.)
Resource description for the surfreport endpoint
Let’s review the surf report wiki page (which contains the information about the resource) and try to describe the resource in 1-3 sentences. Here’s my approach:
Surfreport
Contains information about surfing conditions, including the surf height, water temperature, wind, and tide. Also provides an overall recommendation about whether to go surfing.
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.
