Minimum Viable Documentation

For RESTful APIs

@theMikeJang

Link to GitLab Tech Talk video

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

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

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

@theMikeJang

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

 

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

  1. Landing Pages

  2. Tutorials

  3. Details

  4. Work in Progress

@theMikeJang

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

@theMikeJang

Jordi Cucurull - CC-BY-SA 2.0

  1. 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

Twitter

@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

Nexmo Dev Site

@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