The document outlines various types of API documentation, emphasizing the importance of developer experience, discoverability, and the decision-making process between building or buying documentation tools. It categorizes types of documentation into tutorials, how-to guides, explanations, and references, advocating for organizing docs by features rather than types. The text also addresses the integration of documentation with existing developer tools and SEO strategies for better discoverability.

1. Documenting APIs
from 406 Not Acceptable
to 200 OK

2. Any carrier
Any marketplace
James Messinger
Product Director
@James_MessingerJamesMessinger

3. Documenting APIs | Agenda
● Types of documentation
● Developer experience
● Discoverability
● Build or Buy?

4. Types of Documentation
Documenting APIs

5. Types of Documentation
Tutorial
● is learning oriented
● is a lesson
● allows newcomers to get started
How-To Guide
● is goal oriented
● is a series of steps
● shows how to solve a problem
Explanation
● is understanding oriented
● explains
● provides background and context
Reference
● is information oriented
● Is accurate and complete
● describes the machinery
Source: https://www.divio.com/blog/documentation

6. Types of Documentation | Spectrum
Source: https://www.divio.com/blog/documentation
How-To Guide
Most useful when learning Most useful when coding
PracticalStepsGeneralKnowledge
problem oriented
Reference
information oriented
Explanation
understanding oriented
Tutorial
learning oriented

7. Types of Documentation | Priority
● Table stakes
● Auto-generatable
● Sufficient for internal
APIs
1 Reference
● Solutions for common
use cases
● Reduces onboarding
time
● Hand-written
2 How-To Guide
● Makes your API more
approachable
● Long-form
● Hand-written
3
Tutorial &
Explanation

8. Types of Documentation | Organization
Organize your docs by feature or use case, not by type.
Give users one place to go, not four.
Tutorial
● Feature 1
● Feature 2
● Feature 3
How-To ReferenceExplanation Tutorial
● Feature 1
● Feature 2
● Feature 3
How-To ReferenceExplanation
Tutorial
● Feature 1
● Feature 2
● Feature 3
How-To ReferenceExplanationTutorial
● Feature 1
● Feature 2
● Feature 3
How-To ReferenceExplanation
● Feature 1
● Feature 2
● Feature 3
Tutorial
How-To
Reference
Explanation
Tutorial
How-To
Reference
Explanation
Tutorial
How-To
Reference
Explanation

9. Developer Experience
Documenting APIs

10. Postman Collection OpenAPI Definition
JSON Schemas
Run in Postman Button
Developer Experience | Beyond Documentation
Integrate with the tools developers are already using

11. Developer Experience | Native SDKs
● Familiar
● Beginner friendly
● Reduced onboarding time
● Improved productivity
● Keep focus on functionality, not
implementation
● Promotes community
● Not just an API client
● Ensure best practices
● The primary method of using your API

12. not endpoints & verbs
Developer Experience | Native SDKs
The primary method of using your API
Provide first-class SDK docs Complete code samples
Code samples should use SDKs Installation instructions
Separate docs for each language IDE & editor screenshots
Project templatesClasses & methods

13. Discoverability
Documenting APIs

14. Discoverability
Search engine optimization Increased product awareness
Shareability Organic growth
Analytics Spot popular topics, trends, flows
Your documentation is part of your content strategy

15. Discoverability | Metadata
WebAPI & APIReference
JSON-LD
used by more than just Twitter
requires a server used by more than just Facebook
Twitter cards
OpenGraphoEmbed
embed cards, content preview
Shareable
enrich search results with context
Customize search engine results

16. Discoverability | Page Per Topic
popular topics, related topics, flow
smaller pages, less memorybookmark individual topics
separate embed cards for each topic better user experience + seo
Analytics
Shareable Faster load times
Bookmarkable Mobile optimized
separate index entries for each topic
Search engine optimization

17. Discoverability | Progressive Enhancement
pages should be usable while JS loads
even if JavaScript fails or errors
previews only includes static content
crawlers don’t always run JS
progressive features are optional
Faster load timesSearch engine optimization
Mobile optimizedUnfurl friendly
Content still loads
for loading content or navigation
Don’t rely on JavaScript

18. Build or Buy?
Documenting APIs

19. Build or Buy? | Reasons to Buy
The API ecosystem is rich with documentation builders
and end-to-end API lifecycle tooling

20. Faster time to market
Focus on core product offering
Reduce initial costs
No competitive advantage gained
Limited budget
Already proven solutions
Integrations
Internal API
Feature complete
Lack of expertise
Build or Buy? | Reasons to Buy

21. It’s never been easier to build your own API docs
Build or Buy? | Reasons to Build

22. Flexibility and control
Product differentiator
Competitive advantage
No vendor lock-in
Personalization
Increased productivity
Nonstandard API
Workflow integrationSpecialized requirements
Search engine optimization
Build or Buy? | Reasons to Build

23. ● API as product
● Product differentiator
● Dedicated DX team
● API as feature
● Internal APIs
● Early stage product
Build Buy
Build or Buy?

24. Questions?
Documenting APIs

25. Documenting APIs
from 406 Not Acceptable
to 200 OK