Minimal Viable Documentation for RESTful APIs
@theMikeJang
API the Docs Virtual Conference, 22 April 2020
CC0
Minimum Viable Documentation
For RESTful APIs
@theMikeJang
https://slides.com/mike-1/minimum-viable-documentation
Follow Along
https://slides.com/mike-1/minimum-viable-documentation/live#
https://slides.com/mike-1/minimum-viable-documentation
Online Copy
@theMikeJang
Documentarian
(aka Technical Writer)
-
Identity and Access Management
-
Author (see Amazon)
-
RHCE
-
Write the Docs Meetups
CC0
@theMikeJang
Audience
-
Writers
-
Content Creators
CC0
@theMikeJang
MVD
Minimum Viable Documentation
@theMikeJang
Spoiler: It's all about the DX
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
Walls
of
Text
self-created screenshots
What's
The
Difference?
self-created screenshot
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
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
Keep It Simple
@theMikeJang
Minimal Viable Documentation (MVD)
@theMikeJang
credit: @kvantomme
MVD Details
-
Landing Pages
-
Tutorials
-
Details
-
Work in Progress
@theMikeJang
@theMikeJang
Jordi Cucurull - CC-BY-SA 2.0
-
Landing Pages
RESTful API Feeder
@theMikeJang
Credit: Eldood64151 CC-BY-SA 4.0
Examples
@theMikeJang
Screenshot self-created
@theMikeJang
Screenshot self-created
Stripe
Takeaways
Landing Pages
@theMikeJang
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
(Real World)
@DevportalAwards nominee
Customization
Public Domain
CC0
Custom URLs
and
Code
Samples
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
3. Details
screenshot self-created
@theMikeJang
Under the Hood
CC0
Make it Easier
-
Respect Newer Users
-
Organized Endpoints (not all in one page)
-
When in doubt, curl it out
-
UX Quality
Respect Newer Users
@DevportalAwards nominee - Erste API Hub
@theMikeJang
Organized Endpoints
@theMikeJang
Anyone can curl
Stripe API site
@theMikeJang
Good UX -> Good DX
Takeaways
Details
Action Plan
(3. Details)
-
Explain the Basics
-
Organized Endpoints (no Walls of Text)
-
Minimum requirement: curl
-
Respect the DX
4. Work in Progress
Sharing Hope
Work in Progress
-
Release Notes
-
Blogs
-
Roadmaps
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
Action Plan
(4. Work in Progress)
-
Release Notes
-
Blogs
-
Road Maps
MVD
https://slides.com/mike-1/minimum-viable-documentation
Online Copy
@theMikeJang
Thanks!
@theMikeJang
@katie_the_dog
Questions
@theMikeJang
Minimum Viable Documentation for RESTful APIs
By Mike
