API documentation can make or break developer experience
At this week's API World, experts highlight issues with poor API documentation and suggest ways to fix it, such as ditching jargon and adopting the OpenAPI Specification.
SAN JOSE, Calif. -- API documentation gives developers a written guide for how to use programming interfaces, but if done poorly, it can create roadblocks for others, industry experts said at this week's API World conference.
APIs allow applications and platforms to interact, orchestrating communication between apps with different underlying architectures. Behind every API is a complex layer of information, such as API calls, data formats, requests and syntax. Best practices dictate that API documentation should contain all the information necessary for another developer to understand an API's features and functionality, such as code examples, screenshots, syntax references and other pertinent information.
Good documentation is especially vital now, given flux in the job market caused by the Great Resignation, said Tom Peelen, senior solution engineer at automated testing platform Sauce Labs, during an API World session.
"You have an abundance of people swapping jobs," he said. "If you don't have a solid formula to follow, it takes longer for a new person to ramp up."
Poor-quality documentation can cause significant problems for developers, especially when it comes to API testing, as it can create a lack of consistency from test to test and negatively affect team collaboration and developer productivity, Peelen said.
You have an abundance of people swapping jobs. If you don't have a solid formula to follow, it takes longer for a new person to ramp up.
Tom PeelenSenior solution engineer, Sauce Labs
"You need to make sure that new employees know how these API tests were built out and that they have a foundation to pull from that is consistent," he said.
The challenge of good API documentation
API documentation is difficult to get right, said conference attendee Rob Zazueta, a freelance technical consultant based in Concord, Calif.
Good API documentation can be easily understood by other developers, stays connected with the code and is searchable. However, every company has its own jargon, which can become problematic for external developers trying to read someone else's terminology.
"One of the biggest challenges for API developers is being able to take that internal model of their world and communicate it in a way that everyone can understand it," he said.
In addition to documenting the code, developers must also document the interface. "For external users, I have to be careful about the terminology I'm going to use, and I usually have to overexplain," Zazueta said. For example, developers must be willing to document what the interface is doing and what the use cases are, he said.
The OpenAPI Specification can alleviate many of the troubles with poor documentation, said Rosie Cunningham, developer evangelist at Dropbox, during a session at API World.
Rosie Cunningham shares tips to improve API documentation at API World this week.
The specification defines a programming language-agnostic interface for describing and documenting APIs. The simple text file allows anyone to understand an API's inner workings, including users.
"It's easy to implement, easy to use and easy to get started with," Cunningham said.
The Dropbox team made several other improvements to documentation, including adopting a documentation-as-code approach, she said. Docs-as-code is a philosophy where developers write documentation using the same tools they use to code.
In addition, the Dropbox Sign API is, unlike its predecessor, fully searchable. Searchable documents make working with APIs easier for everyone from developers to end users, Cunningham said. Engineers saw benefits such as increased velocity and a better ability to maintain APIs, she said.
Searchability also brings an additional bonus to developers and nondevelopers alike: improved vulnerability hunting. "Because of expanded documentation, nonengineers can find bugs faster," Cunningham said.
