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.
Until this point, you’ve been acting as a developer with the task of integrating the weather data into your site. The point was to help you understand the type of information developers need and how they use APIs.
Now let’s shift perspectives. Now suppose you’re a technical writer working with the OpenWeatherMap team. The team is asking you to document a new endpoint. What do you cover, and how do you approach it?
The project manager calls you over and says the team has a new endpoint for you to document for the next release. (Sometimes teams will also refer to each endpoint as an “API” as well.)
“Here’s the wiki page that contains info about the new API,” the manager says. The information is scattered and random on the wiki page.
Most technical writers don’t start from scratch with documentation projects. Engineers usually dump essential information onto an internal wiki page (or they communicate the info during meetings). However, the information on the wiki page will likely be incomplete and unnecessarily technical in places (like describing the database schema or high-level architectural workflows). The info might also include internal-only information (for example, test logins, access protocols, or code names) or have sections that are out-of-date.
Ultimately, the information will be oriented towards other engineers on the same knowledge level as the team’s engineers. Your job as a technical writer will be to take this information and turn it into complete, accurate, usable information that communicates with your audience.
It’s now your task to sort through the information on this mock wiki page and create documentation from it. You can read through the mock wiki page below to get a sense of the information. In the upcoming topics, we will proceed section by section through an API reference topic.
Here’s the mock internal wiki page:
The wiki page: "Surf Report API"
The new endpoint is /surfreport/{beachId}. This endpoint is for surfers who want to check things like tide and wave conditions to determine whether they should head out to the beach to surf. {beachId} is retrieved from a list of beaches on our site.
Optional parameters:
Number of days: Max is 7. Default is 3. Optional.
Units: imperial or metric. With imperial, you get feet and knots. With metric, you get centimeters and kilometers per hour. Optional.
Time: time of the day corresponding to time zone of the beach you're inquiring about. Format is unix time, aka epoch. Unix time is the milliseconds since 1970. Time zone is GMT or UTC. Optional.
If you include the hour, then you only get back the surf condition for the hour you specified. Otherwise, you get back 3 days, with conditions listed out by hour for each day.
The response will include the surf height, the wind, temp, the tide, and overall recommendation.
recommendation - string ("Go surfing!", "Surfing conditions okay, not great", "Not today -- try some other activity.")
The recommendation is based on an algorithm that takes optimal surfing conditions, scores them in a rubric, and includes one of three responses.
Sample format:
{"surfreport":[{"beach":"Santa Cruz","monday":{"1pm":{"tide":5,"wind":15,"watertemp":60,"surfheight":5,"recommendation":"Go surfing!"},"2pm":{"tide":-1,"wind":1,"watertemp":50,"surfheight":3,"recommendation":"Surfing conditions are okay, not great"}...}}]}
Negative numbers in the tide represent incoming tide.
The report won't include any details about riptide conditions.
Although users can enter beach names, there are only certain beaches included in the report. Users can look to see which beaches are available from our website at https://example.com/surfreport/beaches_available (not a real URL). The beach names must be url encoded when passed in the endpoint as query strings.
To switch from feet to metrics, users can add a query string of &units=metrics. Default is &units=imperial.
Here's an example of how developers might integrate this information. This site shows the height of the surf coupled with a cam.
If the query is malformed, you get error code 400 and an indication of the error.
You can see that the information here is unstructured and hard to scan. By structuring the API reference information into five standard sections, the information will take more shape and be more readable.
Next steps
Let’s jump into the API reference tutorial overview for an overview of the five steps we’ll cover in creating the API reference topic for this new endpoint.
About Tom Johnson
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.
