Introducing The Good Documentation Checklist

Joyce

October 27, 2020

LAST UPDATED ON: May 3, 2022

I’ve previously talked about the traits of a good collection. While not all collections grow up to be documentation, collections are the foundational building blocks for all Postman documentation viewable on the web. Here, I’m going to talk about the traits of good API documentation.

Postman documentation has become widely adopted across the API community because it enables better collaboration and API adoption. Let’s learn from the thousands of publishers who document their APIs in Postman—like Microsoft, Twitter, and Dropbox—and find out what makes their documentation successful.

What is good documentation?

Related: Document your API like a pro

Effective documentation teaches someone how to use your API. Since the intended audience is people, and not machines, effectiveness is a subjective measure. Still, we can find some shared similarities across good documentation.

Take a look at this breakdown of nine helpful documentation tips and see how your own process measures up. In true Postman fashion, I’ve documented these guidelines in a collection. You can experience an interactive version of this blog post in The Good Documentation Checklist template, which is comprised of examples from publishers who document their APIs in Postman.

1. Create a Postman Collection

• Generate from an API specification: If you’re using an API specification format, such as OpenAPI, you can import a spec file into Postman to automatically generate a collection. Once you have a collection, you can automatically generate web-viewable Postman documentation.
• Find a collection: It’s possible someone else has already done the heavy lifting of creating a collection. Check with your teammates to see if they have a collection that can provide a starting point for the full-fledged collection. Or, you may discover that community members are sharing unofficial collections documenting your public API.
• Start from scratch: If you’re starting from scratch, you can import cURL as raw text for each API call. Or as a last resort, input every endpoint’s URL, method, etc.

2. Organize the API metadata

• Verify the request metadata: If you previously used a machine-readable data format, consider renaming your requests to be more human-readable. Verify the API metadata (e.g. method, URL, headers) displays in the way you want.
• Organize logically in folders: If your collection contains lots of requests, stay clean and tidy by ordering and grouping requests in folders to make the documentation easier to navigate.
• Add and format descriptions: Provide a description for each parameter, request, folder, and collection. Style your descriptions, add tables, and embed screenshots using Markdown so readers can quickly identify the most relevant details. You will author the content inside Postman in Markdown, but consumers will view it in the web browser as HTML.

3. Include a Getting Started guide

• Add headings in the Introduction: The collection description should include relevant information about rate limiting, content types, or settings that apply across endpoints. Any h1 heading that you add to the collection description automatically displays in the side navigation. This makes it easier for the reader to scan for important sections of the documentation.
• Explain authorization: The collection description is also a good place to be explicit about how to authorize requests—including instructions explaining what developers need to do to acquire and use credentials. Additionally, Postman has auth helpers under the Authorization tab to help get users interacting with your API quickly. Some publishers choose to manually add authorization headers under the Headers tab of a request, but you can also add an authorization type for an entire folder or collection.

4. Keep it DRY with variables

• Use variables: Just like in programming, Postman variables make it easy to change a value in one spot and propagate those changes throughout a collection so you can keep your code DRY (Don’t Repeat Yourself) instead of WET (Write Everything Twice).
• Consider variable scopes: Postman supports several variable types and scopes to support different scenarios. For example, a collection variable is useful when the value is inextricably linked to a particular collection. Environment variables can be decoupled from the collection to be used with another collection (e.g. user authorization tokens or server configuration details).
• Add placeholder text: Postman relies on string substitution to render variable values in the web documentation. Use placeholder text as a variable’s value to indicate what value to use. If you leave the value blank, Postman displays no information in the documentation.

5. Show use cases

• Provide examples: Save examples of requests and responses so users can understand the endpoint and troubleshoot issues more quickly. This is especially useful when a user is browsing the documentation and doesn’t yet have their access credentials. Ensure that these examples contain readable, prototypical usage of your API endpoints.
• Demonstrate scenarios: Good documentation is more than just API reference. It includes user scenarios to show what is possible with the API. Guide new users through the proper sequence of API calls to accomplish a specific workflow using variables to pass along data. These use cases can be grouped in folders or as a stand-alone collection.

6. Be secure

• Use variables for secrets: Another great use for variables is to store your secrets instead of hard-coding your confidential data. Remember to update your secrets with placeholder text, so you don’t leak any confidential information.
• Set up a sandbox environment: Some publishers have an isolated testing environment called a sandbox. This allows users to play around with the API without incurring any costs or side effects in a production environment. You can show users how to interact with your sandbox by pre-populating a collection and environment with the sandbox domain and test credentials.

7. Share private API documentation

• Collaborate with teammates: Share your API documentation with teammates by sharing the collection to a team workspace. The default role is that anyone is a “Viewer” of the collection but you can grant “Editor” capabilities to trusted team members. Fork and then merge the collection so you can choose when to work independently versus collaboratively.

8. Share public API documentation

• Publish the documentation: In addition to sharing API documentation privately, you can also share collections and environments publicly as web-viewable documentation. Documentation is based on a Postman collection, so you can generate it from an existing collection or create it in conjunction with a new collection.
• Embed the Run in Postman button: The Run in Postman button is one way to share a Postman collection (and optional environment). This button is found in the Postman API Network, at the top of published documentation in the web, and also where publishers embed the stand-alone button (like in a README or developer portal).
• Add it to the API Network: When you share API documentation publicly, you can also list those collections in the Postman API Network for broader discovery. Make sure to add a concise description and tags so users can easily identify relevant APIs.
• Spruce up your profile: When you publish a collection, you can do that from either a personal profile or team profile. Taking the time to fill out your team profile gives readers a clear sense of who a collection is published by helping them to decide whether to try it out or not. You can add a name, description, photo, and custom URL.

If you’ve ticked most of these boxes, then you can confidently say that you have good documentation. For all you overachievers, let’s forge ahead to a bonus round.

9. Advanced stuff

• Add scripts: You can add JavaScript that executes before or after a request runs. These pre-request and test scripts are useful for setting and getting variable values. Writing scripts is also good for debugging, like logging output to the console. If you find yourself reusing a lot of scripts, you can add them to entire collections or folders to run along with every request within that collection or folder.
• Keep track of metrics: Postman displays some information like views and imports of your documentation collection. Some publishers will add a custom header to requests in their Postman collection for the purpose of inspecting traffic that comes from the Postman client. This gives them more traceability and insights into how users are interacting with their endpoints from Postman.
• Helpful error messages: Publishers have developed clever ways to provide feedback to users who are learning their APIs. Some use helpful error messages returned from the server to guide users along their journey. Others rely on Postman log statements or tests to interpret the client request or standard server response and prompt users to update their API call appropriately.
• Visualize the API response: Another way you can make each API request more informative is to use the Postman Visualizer to visualize the response or provide more detail about what actions can be taken next by the API consumer. Providing built-in visualizations and responses can guide consumers through the API’s highlights, making it more of a hands-on journey.

More examples of good documentation

If you’re looking for benchmarks of good documentation collections, check out these stars:

• Ping Identity has a number of public APIs listed on their Ping Identity team profile page. In the PingOne Platform APIs collection, endpoints are organized neatly into folders, markdown tables summarize required and optional variables, and technical diagrams provide a general overview for readers.
• Dropbox has a single documentation collection with workflows for team admins listed on their Dropbox team profile page. This collection is unique in that it’s not intended for API reference, but rather for Dropbox team admins to execute specific workflows and tasks. The collection is kind of like an admin panel or internal tool, executing scripts in Postman.
• Twitter has two profile pages for their Developer Labs and Twitter Ads teams. For the Twitter API v2, they’ve included examples demonstrating practical scenarios like 429 Rate limit exceeded and 200 Request Tweet fields. When you import this collection, you can also see a collection-level script that runs before every request in the collection to retrieve a Bearer token from the client credentials that you provide in your environment file.
• Rich Data Services provides a wealth of information with their data APIs, providing all the information you need to understand what is being offered with their COVID-19 APIs. Notice that every API request has a visualization that guides you through how to use each individual API.

Many of the better practices we’ve talked about are universal truths about docs, whether or not you’re documenting your APIs with Postman. If you’ve read this far, chances are you’re thinking about investing in proper onboarding and developer education for your APIs.

Come on over and join the Postman API Network. Or dig deeper into documentation best practices and check out this post I wrote about The Ultimate API Publisher’s Guide. If you’re doing something neat with API documentation, let us know in a comment below so that we can share it with the rest of the Postman community.