Minimum Viable Documentation
For RESTful APIs
@theMikeJang
Minimal Viable Documentation for RESTful APIs
@theMikeJang
CC0

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

CC0
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
Audience
-
Admins
-
Developers
-
Writers
-
Content Creators

CC0
@theMikeJang
MVD
Minimum Viable Documentation
@theMikeJang
Spoiler: It's all about the DX


https://slides.com/mike-1/mvd-api-docs-2020
Developers are People Too

Why Documentation?

@theMikeJang
search engine screenshot
But it's Self-Documenting!
Self-Documenting Code

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)


@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020


Walls
of
Text
self-created screenshots



How To Learn A New Language



It's a Foundation

CC0
@theMikeJang
Time For MV Docs

Public Domain
@theMikeJang
Good DX
https://devportalawards.org/
@theMikeJang
credit: @kvantomme

RESTful
API

CC0
pexels.com/photo-license

Secret
Good DX = f(UX)

@theMikeJang
credit: The Onion

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

Ideal World Documentation

@theMikeJang
credit: @kvantomme

Real World

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)

@theMikeJang
credit: @kvantomme

MVD Details
-
Landing Pages
-
Tutorials
-
Details
-
Work in Progress
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020

@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

@theMikeJang
Screenshot self-created
Stripe

Takeaways
Landing Pages
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
f(x) UX
@theMikeJang
Principle

@theMikeJang
credit: Steve Krug
Action Plan
(Landing Pages)
-
Use Cases
-
Lay Out API Functionality
-
Principles of UX
@theMikeJang
2. Tutorials

@theMikeJang
Pic 1: CC0
Pic 2: Intel Free Press,
CC BY-SA 2.0

Tutorials (Samples)
-
Use Cases (Extended)
-
Customization *
-
Test Playgrounds *
@theMikeJang
* Beyond MVD
Use Cases
(Buffet)

CC0
@theMikeJang
Use Cases
(Real World)
@DevportalAwards nominee
@theMikeJang

Orange Developer Site

Use Cases
@DevportalAwards nominee

Customization

Public Domain

CC0
Test Playground
@theMikeJang
fair use




Remember That Foundation

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

screenshot self-created
@theMikeJang
Under the Hood

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

@DevportalAwards nominee - Erste API Hub
@theMikeJang
Organized Endpoints

@theMikeJang
ForgeRock API Explorer
Anyone can curl

Stripe API site
@theMikeJang
Enable Demo Environments
Ayden API site
@theMikeJang



GraphQL Explorer
@theMikeJang






Good UX -> Good DX
https://slides.com/mike-1/mvd-api-docs-2020
@theMikeJang
Takeaways
Details
@theMikeJang


@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

public domain
@theMikeJang
What's New
What's Changed
Blogs
@theMikeJang

public domain
Relatable
Conversational
Road Maps
@theMikeJang

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://slides.com/mike-1/mvd-api-docs-2020
Online Copy
@theMikeJang
Git
Lab

@katie_the_dog
Thanks!
@theMikeJang
https://slides.com/mike-1/mvd-api-docs-2020
Minimum Viable Documentation for RESTful APIs
By Mike
Minimum Viable Documentation for RESTful APIs
For API the Docs Conference, Virtual Edition, 22 April
- 2,856