This document provides tips for upgrading API documentation collections in Postman. It recommends including collection-level context, user stories, example responses, visualizations, and utility requests to create well-documented collections. Context such as the creator, technical specifications, and resources helps users understand what the collection contains and whether it fits their needs. User stories, examples, and visualizations help lower barriers to entry and build user confidence. Utility requests allow for flexible scripting. Well-documented collections benefit users, developers' future selves, and others in the community.

1. Upgrade Your
Collections
Practical tips to take
your documentation to
the next level.
Carson Hunter
Software Developer
@carrrson / @mtnaus

2. 2
3 4
1
Postman Resource
Centers / Public
Workspaces
Postman Search
Who benefits from good docs?
Your users
TLDR: everyone.
Your future self
@carrrson

3. Postman Public Workspaces &
API Resource Centers
Create a
Utility
Submit your
own API
Document
Someone Else's
@carrrson

4. postman.com/mtnateam
postman.com/mtnateam
Use as a guide /
checklist
Or as a basis for your
own collection
The Submission
Template
@carrrson

5. 1
2
3
Context
Example Responses
Stories
4 Visualizations
5 Utility Requests
What makes a
well-documented
collection?
@carrrson

6. 1
Collection-Level Context
Provenance
Creator Info
Tech Specs
Resources
@carrrson
Is it
the
right
fit?

7. 2
User Stories
Lowers the barrier
to entry
A chance to guide
& teach users
@carrrson

8. 3
Example Responses
Highlight
Multiple
Responses
MTNA Newman
Utility
Build
Confidence
@carrrson
github.com/mtna/
postman-utils

9. 4
Visualizations
Insert a picture or GIF
+ instructions
@carrrson
Gives users a head
start

10. 5
Utility Requests
Flex your JavaScript muscles
script
magic
@carrrson

11. Resources
Submission Template:
https://www.postman.com/mtnateam
MTNA Newman Example Response Utility:
https://github.com/mtna/postman-utils
COVID Resource Center:
https://postman-toolboxes.github.io/covid-19/
COVID Public Workspace:
https://www.postman.com/postman/workspace/covid-19
carson.hunter@mtna.us
@carrrson
@mtnaus