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