Documenting APIs · Organize your docs by feature or use case, not by type. Give users one place to...

30
Documenting APIs from 406 Not Acceptable to 200 OK

Transcript of Documenting APIs · Organize your docs by feature or use case, not by type. Give users one place to...

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

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

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

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

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

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

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

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

https://www.divio.com/blog/documentation/
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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

● 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

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

Documenting APIsfrom 406 Not Acceptable to 200 OK


Documenting Life

Documenting Life

Documenting Clinical Interventions in Community Pharmacy ...6cpa.com.au/wp-content/uploads/Documenting-Clinical-Interventions... · Documenting Clinical Interventions in Community

Documenting Clinical Interventions in Community Pharmacy ...6cpa.com.au/wp-content/uploads/Documenting-Clinical-Interventions... · Documenting Clinical Interventions in Community

General Guidance for Developing, Documenting, Implementing ... · PDF fileGeneral Guidance for Developing, Documenting, ... The purpose of SQF Code implementation is not only to achieve

General Guidance for Developing, Documenting, Implementing ... · PDF fileGeneral Guidance for Developing, Documenting, ... The purpose of SQF Code implementation is not only to achieve

Documenting Process Calibrator - Flukeassets.fluke.com/manuals/741b743bumeng0100.pdf · Documenting Process Calibrator Introduction Fluke 741B and 743B Documenting Process Calibrators

Documenting Process Calibrator - Flukeassets.fluke.com/manuals/741b743bumeng0100.pdf · Documenting Process Calibrator Introduction Fluke 741B and 743B Documenting Process Calibrators

Documenting Systems

Documenting Systems

documenting source

documenting source

It's not a bug, it's a feature!

It's not a bug, it's a feature!

Documenting First

Documenting First

Not for profit feature artical

Not for profit feature artical

Documenting PROGRAMA

Documenting PROGRAMA

documenting work

documenting work

Methodological Proposals for Documenting and … · Methodological Proposals for Documenting and Searching ... Clandestine Burials ... Methodological proposals for documenting and

Methodological Proposals for Documenting and … · Methodological Proposals for Documenting and Searching ... Clandestine Burials ... Methodological proposals for documenting and

Documenting Lives

Documenting Lives

2015 Diagnosing, Documenting and Coding Chronic Conditions ... · Proprietary and Confidential. Do not distribute. 2015 Diagnosing, Documenting and Coding Chronic Conditions for Risk

2015 Diagnosing, Documenting and Coding Chronic Conditions ... · Proprietary and Confidential. Do not distribute. 2015 Diagnosing, Documenting and Coding Chronic Conditions for Risk

Managing Feature Interaction by Documenting and …redmiles/publications/C070-S-FR07.pdfsoftware engineers in their extension and configuration. Keywords: Feature interaction, software

Managing Feature Interaction by Documenting and …redmiles/publications/C070-S-FR07.pdfsoftware engineers in their extension and configuration. Keywords: Feature interaction, software

＜nanjing massacre＞There Is Not a Single “Real Photograph” Documenting the Nanking Incident

＜nanjing massacre＞There Is Not a Single “Real Photograph” Documenting the Nanking Incident

Documenting the Mined Feature Implementations from the Object-oriented Source Code of a Collection of Software Product Variants

Documenting the Mined Feature Implementations from the Object-oriented Source Code of a Collection of Software Product Variants

Documenting Riemann'SCOMPLEX

Documenting Riemann'SCOMPLEX

Documenting Python

Documenting Python

Suggestions for Documenting SOA-Based Systems · 5.2 Future QoS Needs Are Not Known at Design Time 15 ... 6 Suggestions for Documenting SOA-Based Systems 19 ... Manually Document

Suggestions for Documenting SOA-Based Systems · 5.2 Future QoS Needs Are Not Known at Design Time 15 ... 6 Suggestions for Documenting SOA-Based Systems 19 ... Manually Document