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.
The first step to testing your instructions is to set up a test environment. Without this test environment, it will be difficult to make any progress in testing your instructions.
The kind of test environment you set up depends on your product and company. In the following sections, I explain testing setup details for different scenarios:
The easiest way to test an API is by making requests to a test server where the API service is configured. QA can usually help you with access to the test server. With the test server, you’ll need to get the appropriate URLs, login IDs, roles, etc. Ask QA if there’s anything you shouldn’t alter or delete because sometimes the same testing environment is shared among groups.
Additionally, make sure your logins correspond with the permissions users will have. If you have an admin login, you might not experience the same responses as a regular user.
You may also need to construct certain files necessary to configure a server with the settings you want to test. Understanding exactly how to create the files, the directories to upload them to, the services to stop and restart, and so on, can require a lot of initial investigation.
Exactly what you have to do depends on your product, the environment, the company, and security restrictions, etc. No two companies are alike. Sometimes it’s a pain to set up your test system, and other times it’s a breeze.
At one company, to gain access to the test system, we had to jump over a series of security hurdles. For example, connections to the web services from internal systems required developers to go through an intermediary server. To connect to the web server test instance, you had to SSL to the intermediary server, and then connect from the intermediary to the web server. (This wasn’t something users would need to do, just internal engineers.)
The first time I attempted this, I asked a developer to help me set this up. I carefully observed the commands and steps he went through on my computer. I later documented it for future knowledge purposes, and other engineers used my doc to set up the same access.
Testing local builds
Many times, developers work on a local instance of the system before pushing it to a test server. In other words, they build the app or web server entirely on their own machines and run through test code there, long before pushing it to a test server. If you’re plugged into the project this early, great — you might have more influence on the API’s design and can influence changes as needed. To build code locally, you may need to install special utilities or frameworks, become familiar with various command line operations to build the code, and more.
If you can get the local builds running on your own machine, it’s usually worthwhile because it can empower you to document content ahead of time, long before the release.
If it’s too complicated to set up a local environment, you can ask an engineer to install the local system on your machine. Sometimes developers like to just sit down at your computer and take over the task of installing and setting up a system. They can work quickly on the command terminal and troubleshoot systems or quickly proceed through installation commands that would otherwise be tedious to walk you through.
Many times, developers aren’t too motivated to set up your system, so they may give you a quick explanation about installing this and that tool. But never let a developer say “Oh, you just do a, b, and c.” Then you go back to your desk and nothing works, or it’s much more complicated than he or she said it would be. It can take persistence to get everything set up and working the first time.
If a developer is knee-deep in sprint tasks and heavily backlogged, he or she may not have time to help you properly get set up. Be patient and ask the developer to indicate a good time to go over the setup.
With local builds, setting up a functional system is much more challenging than using a test server. Still, if you want to write good documentation, setting up a test system is essential. Good developers know and recognize this need, and so they’re usually accommodating (to an extent) in helping set up a test environment to get you started.
Testing sample apps
Depending on the product, you might also have a sample app or SDK in your code deliverables. You often include a sample app or SDK (or multiple apps and SDKs in various programming languages) with a product to demonstrate how to integrate and call the API. If you have a test app that integrates the API, you’ll probably need to install some programs or frameworks on your own machine to get the sample app working.
For example, you might have to build a sample Java app to interact with the system — so you’d likely need to have the Java Development Kit and a Java IDE installed on your computer to make it work. If the app is in PHP, you probably need to install PHP. Or if it’s an Android app, you will probably need to download Android Studio and connect it to virtual (or actual) device.
There are usually fewer instructions about how to run a sample app because developers assume users will already have these environments set up on their machines. (It wouldn’t make sense for a user to choose the Java app if they didn’t already have a Java environment, for example.)
The sample app is among the most helpful pieces of documentation. As you set up the sample app and get it working, look for opportunities to add documentation in the code comments. At the very least, get the sample app working on your own computer and include the setup steps in your documentation.
Testing hardware products
If you’re documenting a hardware product, you’ll want to secure a device that has the right build installed on it. Big companies often have prototype devices available. At some companies, there may be kiosks where you can “flash” (quickly install) a specific build number on the device. Or you may send your device’s serial number to someone who manages a pool of devices that receive beta-version updates from the cloud.
With some hardware products, it may be difficult to get a test instance of the product to play with. I once worked at a government facility documenting a million-dollar storage array. The only time I was allowed to see the storage array was by signing into a special data server room environment, accompanied by an engineer, who wouldn’t dream of letting me actually touch the array, much less swap out a storage disk, run commands in the terminal, replace a RAID, or do some other task (for which I was writing instructions).
I learned early on to steer my career towards jobs where I could actually get my hands on the product, usually software code, and play around with it. When I was working at Amazon, I had a drawer full of Fire TV devices and prototypes. I happened to work in the Amazon devices section, so I had almost every model of Fire TV, Echo Dot, Echo Spot, Echo Show, TVs with Fire OS, and more. Through Android Studio and Android Debug Bridge (ADB), I would run an app on one of these physical devices to test how it works. It’s a lot of fun to play around with different devices.
If you’re documenting hardware, you need access to the hardware to provide reliable documentation on how to use it. You’ll need to understand how to run apps on the device and how to interface with it. Hopefully, the product is one that you can access to play around with in a direct, hands-on way.
Working at Google, the product I was documenting included Google services, such as Google Maps, Play Store, and Assistant, embedded directly in the car’s infotainment system. These services are built on the Android operating system. The group I was in maintained a fleet of vehicles, mostly Volvo Polestars and XC-90s, with test installs of Android and these Google services. One day I decided to check a fleet car out and drove it around for a couple of weeks. The experience gave me a much better understanding of the product, one that I didn’t entirely possess before when I was just writing about the features. I could experience first-hand in many real situations what the user experience was with the product, and while in some cases I was underwhelmed, in others I was kind of like, wow, this is cool. I logged about 25 bugs while I had the car during this time.
If you encounter developer resistance …
Many times developers don’t expect that a technical writer will be doing anything more than just transcribing and relaying the information given to him or her by engineers. With this mindset, a developer might not immediately think that you need or want a sample app to test out the calls or other code. You might need to ask (or even petition) the developers for it.
I’ve found that most of the time, developers respect technical writers much more if the technical writers can test out the code themselves. Engineers also appreciate any feedback you may have as you run through the system. Technical writers, along with QA, are usually the first users of the developer’s code.
If a developer or QA person can’t give you access to any such test server or sample code, be suspicious. How can a development and QA team create and test their code without a sample system where they expect it to be implemented? And if there’s a sample system, why can’t you also have access so you can write accurate, thorough documentation on how to use it?
Sometimes developers don’t want to go through the effort of getting something working on your machine, so you may have to explain more about your purpose and goals in testing. If you run into friction, be persistent. It might take one or more days to get your test environment set up. For example, it took me several days to get an app framework to build successfully on my Fire TV device. But once you have a test system set up, it makes it much easier to create documentation because you can start to answer your own questions.
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.
