View
4
Download
0
Category
Preview:
Citation preview
Roadmap to Growth How great docs turn users into evangelists
Any carrier
Any marketplace James Messinger
Developer Experience Director
@James_Messinger JamesMessinger
Roadmap to Growth | Agenda
● Different types for
different purposes
● Priority
● Organization
Types of Docs
● Integrating docs into
the development
lifecycle
● Documenting SDKs
Developer Experience
● Docs as part of your
content strategy
● SEO & social media
● Analytics
Discoverability
how great docs turn users into evangelists
Types of Documentation Roadmap to Growth
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
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
Types of Documentation | Organization
Organize your docs by feature or use case, not by type.
Give users one place to go, not four.
Tutori
al
● Fea
ture 1
● Fea
ture 2
● Fea
ture 3
How-
To
Refer
ence
Expla
nation
Tutori
al
● Fea
ture 1
● Fea
ture 2
● Fea
ture 3
How-
To
Refer
ence
Expla
nation
Tutori
al
● Fea
ture 1
● Fea
ture 2
● Fea
ture 3
How-
To
Refer
ence
Expla
nation
Tutori
al
● Fea
ture 1
● Fea
ture 2
● Fea
ture 3
How-
To
Refer
ence
Expla
nation
●Feature 1
●Feature 2
●Feature 3
Tutorial
How-To
Reference
Explanation
Tutorial
How-To
Reference
Explanation
Tutorial
How-To
Reference
Explanation
Developer Experience Roadmap to Growth
Postman Collection OpenAPI Definition
JSON Schemas Run in Postman Button
Developer Experience | Beyond Documentation Integrate with the tools developers are already using
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
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 templates Classes & methods
Discoverability Roadmap to Growth
Discoverability
Search engine optimization Increased product awareness
Shareability Growth & Engagement
Analytics Spot popular topics, trends, flows
Your documentation is part of your content strategy
Discoverability | Metadata
WebAPI & APIReference
JSON-LD
used by more than just Twitter
requires a server used by more than just Facebook
Twitter cards
OpenGraph oEmbed
embed cards, content preview
Shareable
enrich search results with context
Customize search engine results
Discoverability | Page Per Topic
popular topics, related topics, flow
smaller pages, less memory bookmark 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
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 times Search engine optimization
Mobile optimized Unfurl friendly
Content still loads
for loading content or navigation
Don’t rely on JavaScript
API Documentation | Tools
The API ecosystem is rich with documentation tooling
Recommended