Why Documentation?

@theMikeJang

search engine screenshot

Self-Documenting Code

US National Library of Medicine

@theMikeJang

DNA Nucleotides

@theMikeJang

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

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

@theMikeJang

credit: The Onion

Writing for People Who Don't Read

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

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

@theMikeJang

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

Blogs

@theMikeJang

public domain

Road Maps

@theMikeJang

public domain

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