Minimum Viable Documentation
For RESTful APIs
@theMikeJang
Minimal Viable Documentation for RESTful APIs
@theMikeJang
CC0
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5204702/earth-11009_1920.jpg)
Minimum Viable Documentation
For RESTful APIs
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
https://slides.com/mike-1/mvd-api-docs-2020
Online Copy
@theMikeJang
Documentarian
(aka Technical Writer)
-
Manage (IAM, Analytics, Import, Compliance, Spaces)
-
Author (see Amazon)
-
RHCE
-
Write the Docs Meetups
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/3706357/nerd.png)
CC0
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
Audience
-
Admins
-
Developers
-
Writers
-
Content Creators
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/3704620/audience-648476_1920.jpg)
CC0
@theMikeJang
MVD
Minimum Viable Documentation
@theMikeJang
Spoiler: It's all about the DX
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5296485/Screenshot_from_2018-09-25_14-10-14.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7190163/MVP_template_apithedocs.png)
https://slides.com/mike-1/mvd-api-docs-2020
Developers are People Too
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/3704620/audience-648476_1920.jpg)
Why Documentation?
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5172672/JustReadTheCode.png)
@theMikeJang
search engine screenshot
But it's Self-Documenting!
Self-Documenting Code
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173291/DNA.jpeg)
US National Library of Medicine
@theMikeJang
DNA Nucleotides
- Adenine (A)
- Thymine (T)
- Guanine (G)
- Cytosine (C)
REST Commands
- Create (C)
- Read (R)
- Update (U)
- Delete (D)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5218830/HumanGenomeText.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5218844/OpenAPILogo.jpg)
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173329/swagger1.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173328/swagger2.png)
Walls
of
Text
self-created screenshots
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5204702/earth-11009_1920.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5218833/OpenAPI_Logo_Pantone-1.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5217782/Swagger.io.png)
How To Learn A New Language
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5287528/frenchDictionary.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5287544/eiffel-tower-975004_1920.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5217782/Swagger.io.png)
It's a Foundation
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5218864/foundation-2660502.jpg)
CC0
@theMikeJang
Time For MV Docs
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173341/Ernest_Hemingway_Writing_at_Campsite_in_Kenya_-_NARA_-_192655.jpg)
Public Domain
@theMikeJang
Good DX
https://devportalawards.org/
@theMikeJang
credit: @kvantomme
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7190195/DevPortalAwards2020.png)
RESTful
API
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173331/beach-1455815_1920.jpg)
CC0
pexels.com/photo-license
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173352/easy-112316.jpg)
Secret
Good DX = f(UX)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5226046/OnionText.png)
@theMikeJang
credit: The Onion
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173354/nistWallOfText.png)
Writing for People Who Don't Read
Spoiler: People scan docs
https://slides.com/mike-1/mvd-api-docs-2020
@theMikeJang
Help Readers Scan Your Content
- Focus key info in first 2 paragraphs
@theMikeJang
- First 3-5 words are critical
Perspective and DX (UX)
@theMikeJang
CC0
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5227287/shoes-1245920.jpg)
Ideal World Documentation
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5200112/Screenshot_from_2018-08-24_04-49-25.png)
@theMikeJang
credit: @kvantomme
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/3719080/TheScream.png)
Real World
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5201040/deadline-2636259.jpg)
CC0
@theMikeJang
Question
Why Would Anyone Use My API
https://slides.com/mike-1/mvd-api-docs-2020
@theMikeJang
Readers can tell if it works - in seconds
Answer: MVD
Keep It Simple
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
Minimal Viable Documentation (MVD)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5201046/Screenshot_from_2018-08-24_11-55-31.png)
@theMikeJang
credit: @kvantomme
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5200112/Screenshot_from_2018-08-24_04-49-25.png)
MVD Details
-
Landing Pages
-
Tutorials
-
Details
-
Work in Progress
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5201056/16404696856_557e214b34_o.jpg)
@theMikeJang
Jordi Cucurull - CC-BY-SA 2.0
-
Landing Pages
RESTful API Feeder
@theMikeJang
Credit: Eldood64151 CC-BY-SA 4.0
Examples
https://slides.com/mike-1/mvd-api-docs-2020
@theMikeJang
@theMikeJang
Screenshot self-created
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5201147/Screenshot_from_2018-08-24_13-15-16.png)
@theMikeJang
Screenshot self-created
Stripe
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7190354/StripeAPItheDocs2020.png)
Takeaways
Landing Pages
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
f(x) UX
@theMikeJang
Principle
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/3714702/dontMakeMeThink.png)
@theMikeJang
credit: Steve Krug
Action Plan
(Landing Pages)
-
Use Cases
-
Lay Out API Functionality
-
Principles of UX
@theMikeJang
2. Tutorials
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5201250/computerTeacher.jpg)
@theMikeJang
Pic 1: CC0
Pic 2: Intel Free Press,
CC BY-SA 2.0
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5201221/language-lab-181083.jpg)
Tutorials (Samples)
-
Use Cases (Extended)
-
Customization *
-
Test Playgrounds *
@theMikeJang
* Beyond MVD
Use Cases
(Buffet)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5204552/buffet-2251676_1920.jpg)
CC0
@theMikeJang
Use Cases
(Real World)
@DevportalAwards nominee
@theMikeJang
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5211059/Screenshot_from_2018-08-28_13-59-41.png)
Orange Developer Site
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7190631/Orange2020APItheDocs.png)
Use Cases
@DevportalAwards nominee
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7190739/NexmoAPItheDocs.png)
Customization
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5204561/spiceRack.jpg)
Public Domain
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5204573/chefs-729453_1920.jpg)
CC0
Test Playground
@theMikeJang
fair use
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5226631/postman.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5226621/Insomnia.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7220187/RedocLy.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7220190/Stoplight.png)
Remember That Foundation
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5218864/foundation-2660502.jpg)
CC0
@theMikeJang
Takeaways
-
Real World Tutorials
-
Customization
-
Test Playgrounds
@theMikeJang
Action Plan
(2. Tutorials)
-
Use Cases, in a Story
-
Custom URLs, Code Samples
-
Custom Playgrounds for Testing
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
3. Details
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5204782/petstore.png)
screenshot self-created
@theMikeJang
Under the Hood
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5204787/car-engine-1738309_1920.jpg)
CC0
Make it Easier
-
Respect Newer Users
-
Organize Endpoints (not all in one page)
-
When in doubt, curl it out
-
Enable demo environments
-
UX Quality
Respect Newer Users
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5223311/ErsteGroup.png)
@DevportalAwards nominee - Erste API Hub
@theMikeJang
Organized Endpoints
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5224511/APIDescriptorIndex.png)
@theMikeJang
ForgeRock API Explorer
Anyone can curl
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5224569/StripeAPI.png)
Stripe API site
@theMikeJang
Enable Demo Environments
Ayden API site
@theMikeJang
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7201117/Payments1.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7201118/Payments2.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7201119/Payments3.png)
GraphQL Explorer
@theMikeJang
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7201112/jackpot-281423_1920.jpg)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7230869/GraphQL1.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7230868/GraphQL2.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7230867/GraphQL3.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7230865/GraphQL4.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7230866/GraphQL5.png)
Good UX -> Good DX
https://slides.com/mike-1/mvd-api-docs-2020
@theMikeJang
Takeaways
Details
@theMikeJang
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5222284/swagger-logo-horizontal.png)
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5218833/OpenAPI_Logo_Pantone-1.png)
@theMikeJang
Action Plan
(3. Details)
-
Explain the Basics
-
Organized Endpoints (no Walls of Text)
-
Minimum requirement: curl
-
Enable Demo Environments
-
Respect the DX
@theMikeJang
4. Work in Progress
A New Hope
@theMikeJang
Work in Progress
-
Release Notes
-
Blogs
-
Roadmaps
@theMikeJang
Release Notes
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5173341/Ernest_Hemingway_Writing_at_Campsite_in_Kenya_-_NARA_-_192655.jpg)
public domain
@theMikeJang
What's New
What's Changed
Blogs
@theMikeJang
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5207043/Ernest_Hemingway_in_London_at_Dorchester_Hotel_1944_-_NARA_-_192672.jpg)
public domain
Relatable
Conversational
Road Maps
@theMikeJang
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5207074/Lewis_and_Clark_Expo_Map.jpg)
public domain
Future
Plan
Takeaways
Work in Progress
@theMikeJang
Action Plan
(4. Work in Progress)
-
Release Notes
-
Blogs
-
Road Maps
https://slides.com/mike-1/mvd-api-docs-2020
@theMikeJang
MVD
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/5207102/finish_line.jpg)
https://slides.com/mike-1/mvd-api-docs-2020
Online Copy
@theMikeJang
Git
Lab
![](https://s3.amazonaws.com/media-p.slid.es/uploads/631991/images/7208233/GitLabLogo.png)
@katie_the_dog
Thanks!
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020