Better Practices
Published in

Better Practices

The Good Documentation Checklist

See how you measure up to these nine better practices for Postman documentation

What is good documentation?

An interactive version of this blog post in a collection called The Good Documentation Checklist

Step 1. Create a Postman Collection

Generate from an API specification

Find a collection

Start from scratch

Step 2. Organize the API metadata

Verify the request metadata

Organize logically in folders

Add and format descriptions

Twitter API documentation with metadata, examples, and folders

Step 3. Include a Getting Started guide

Add headings in the Introduction

Explain authorization

Dropbox documentation includes headings in the Introduction and explains Authorization using screenshots for more guidance

Step 4. Keep it DRY with variables

Use variables

Consider variable scopes

Add placeholder text

Step 5. Show use cases

Provide examples

Demonstrate scenarios

Step 6. Be secure

Use variables for secrets

Set up a sandbox environment

Step 7. Share private API documentation

Collaborate with teammates

Step 8. Share public API documentation

Publish the documentation

Embed the Run in Postman button

Add it to the API Network

Spruce up your profile

Example of a Team profile page listing multiple collections in the Postman API Network

Step 9. Advanced stuff

Add scripts

Keep track of metrics

Helpful error messages

Visualize the API response

More examples of good documentation

Ping Identity

Dropbox

Twitter

Rich Data Services

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store