Want to Become a Better API Documentation Writer? Read Someone Else’s First
by Robert Delwood, a Lead API Documentation Writer
API documentation writers get very good at writing documentation. But that’s only half or a third of the API experience. The other two aspects are almost completely overlooked. Those two other parts are critical to being empathetic with our client developers. That is, it’s important for writers to know on a functional level how API reference information gets found and used from the guide. You can only get that from reading API documentation. Up until that point, writers are just guessing how information is used. Think how much better writers we can get, or how much more effective the documentation can be, if writers truly understood this from the client’s experience. The two missing parts are:
- Reading API documentation. Reading API documentation is where we learn how clients get information from us, how important formatting and placement consistency is, and how wording makes a difference. Broaden the scope of an API reference and include textbooks from a college class, online sources, or even a friend helping you learn programming, can all be considered API reference guides of a sort. Those all have the information you need and analyze how you get and use that information.
- Developing with the API documentation. The ultimate goal of documentation is using it to create an application. This is an example of how having developer experience is useful for writers. We learn the value of code samples, well-integrated information, why copying and pasting examples is so useful, and how everything in documentation comes together to help client developers. Developing applications using documentation will be covered later articles.
No doubt, reading API documentation is a skill writers need. It’s also something you can start doing now. The following is a sample project to do just that. NASA maintains many APIs, most are free, and some do not registration. Use their Astronomy Picture of the Day API, for example. As the name implies, it offers a selected space photographs for each day. This API retrieves a photo for a specified day, or a range of days, along with a detailed description and other details. This example can be used for learning several topics at the same time. The goals are:
- Learn reading others API guides.
- Use the guide to make your own calls.
- Learn an API tool, such as Postman. Postman (https://www.postman.com/downloads) is a popular API development tool. It lets you make requests and gives you full control over all aspects. I advocate all API documentation writers know Postman and use it frequently to make each request they document. It’s free. You could use a browser for this exercise but consider using Postman. It’s a tool you’ll likely use for any API documentation position.
- Make suggestions to improve the documentation.
For this exercise, follow these steps:
1. Go to https://api.nasa.gov
2. Scroll down the Astronomy Picture of the Day (APOD) section, skipping everything along the way, including the Generate API Key and Authentication sections.
3. Using information only from this APOD section, make a series of at least six requests. Use each of the parameters at least once. As bonus requests, parameters could be combined. For example, to help get things started, the first request should be the one noted in the Example query section:
https://api.nasa.gov/planetary/apod?api_key=DEMO_KEY
That URL is the minimum needed to make a successful request. As a guideline, always begin with the simplest case and work up. In addition, having a request that can be used immediately is an important feature, something I call a quick victory. Readers like seeing immediate results.
4. Along the way, keep notes about the documentation. In trying the requests, you’ll find that this documentation does not do a good job of describing everything. There are notable omissions. In fact, rewrite the document. Use new information you get from making requests. Use your preferences to reword, reorder, re-sequence the documentation, or include the copious use of samples. The goal is to make this API easier for the next person. Make sure they don’t run into the same problems or mistakes you ran into while struggling with missing or misleading information. That’s the point of documentation.
Finally, consider giving your notes to a friend or colleague and see if they can’t follow them without having any problems. If they do have questions or comments, rewrite those sections so they can be understood and followed without exceptions.