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

Beth Hoffman CC BY-NC-SA 2.0

How To Learn A New Language

CHRISTO DRUMMKOPF CC BY-NC-SA 2.0

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

credit: Kevin Burke, Write the Docs 2014

  • 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

  1. Landing Pages

  2. Tutorials

  3. Details

  4. Work in Progress

@theMikeJang

@theMikeJang

Jordi Cucurull - CC-BY-SA 2.0

  1. Landing Pages

RESTful API Feeder

@theMikeJang

Credit: Eldood64151 CC-BY-SA 4.0

Examples

@theMikeJang

Screenshot self-created

Twitter

@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)

Constant Contact Dev Site

@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