documenting apis · organize your docs by feature or use case, not by type. give users one place to...
TRANSCRIPT
![Page 1: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/1.jpg)
Documenting APIsfrom 406 Not Acceptable to 200 OK
![Page 2: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/2.jpg)
Any carrier
Any marketplaceJames Messinger
Product Director
@James_MessingerJamesMessinger
![Page 3: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/3.jpg)
Documenting APIs
● Types of documentation
● Developer experience
● Discoverability
● Build or Buy?
![Page 4: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/4.jpg)
Types of DocumentationDocumenting APIs
![Page 5: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/5.jpg)
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
![Page 6: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/6.jpg)
Types of Documentation
Source: https://www.divio.com/blog/documentation
How-To Guide
Most useful when learning Most useful when coding
Prac
tical
Ste
psG
ener
al K
now
ledg
e
problem oriented
Referenceinformation oriented
Explanationunderstanding oriented
Tutoriallearning oriented
![Page 7: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/7.jpg)
Types of Documentation
● 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
![Page 8: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/8.jpg)
Types of DocumentationOrganize 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
![Page 9: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/9.jpg)
Developer ExperienceDocumenting APIs
![Page 10: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/10.jpg)
Postman Collection OpenAPI Definition
JSON SchemasRun in Postman Button
Developer ExperienceIntegrate with the tools developers are already using
![Page 11: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/11.jpg)
Developer Experience● 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
![Page 12: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/12.jpg)
Developer ExperienceThe 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
![Page 13: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/13.jpg)
DiscoverabilityDocumenting APIs
![Page 14: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/14.jpg)
Discoverability
Search engine optimization Increased product awareness
Shareability Organic growth
Analytics Spot popular topics, trends, flows
Your documentation is part of your content strategy
![Page 15: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/15.jpg)
Discoverability
JSON-LD Twitter cards
OpenGraphoEmbed
ShareableCustomize search engine results
![Page 16: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/16.jpg)
Discoverability
Analytics
Shareable Faster load times
Bookmarkable Mobile optimized
Search engine optimization
![Page 17: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/17.jpg)
Discoverability
Faster load timesSearch engine optimization
Mobile optimizedUnfurl friendly
Content still loadsDon’t rely on JavaScript
![Page 18: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/18.jpg)
Documentation Discoverability
easy to share on
Social Mediaoptimized for
Search Engines
Local Searchwithin your docs
Analyticsto surface relevant docs
![Page 19: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/19.jpg)
Discoverability
One page per topic Page load speed
Cross-link between topics Optimize for mobile
Progressive enhancement JSON-LD
![Page 20: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/20.jpg)
Discoverability
One page per topic Twitter cards
One URL per topic OpenGraph
Allow deep linking oEmbed
![Page 21: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/21.jpg)
Discoverability
One page per topic More specialized
Keep users on your site More contextual
![Page 22: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/22.jpg)
Discoverability
Surface relevant docs
Spot your most popular topics Improve your docs
Analyze behavior flow Make data-driven decisions
One page per topic
![Page 23: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/23.jpg)
Build or Buy?Documenting APIs
![Page 24: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/24.jpg)
Build or Buy?The API ecosystem is rich with documentation builders
and end-to-end API lifecycle tooling
![Page 25: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/25.jpg)
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?
![Page 26: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/26.jpg)
It’s never been easier to build your own API docs
Build or Buy?
![Page 27: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/27.jpg)
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?
![Page 28: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/28.jpg)
● API as product
● Product differentiator
● Dedicated DX team
● API as feature
● Internal APIs
● Early stage product
Build Buy
Build or Buy?
![Page 29: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/29.jpg)
Questions?Documenting APIs
![Page 30: Documenting APIs · 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 Explanation Reference](https://reader034.vdocuments.us/reader034/viewer/2022042322/5f0c55e57e708231d434e469/html5/thumbnails/30.jpg)
Documenting APIsfrom 406 Not Acceptable to 200 OK