Testing: it's not just for code anymore!

My name is Lyzi Diamond. I work on APIs at Mapbox.

The point of this talk: testing is good.

The point of this talk: testing is necessary.

We will talk about:

• The Mapbox API documentation story
• Why our approach worked
• How you can do it too

Part one: The Mapbox API documentation story!

Good documentation pays attention to the small things:

• Consistency
• Completeness
• Correctness
• Contributability

How we did it: docbox and retext-mapbox-standard

(special thanks to tmcw and wooorm for contributing to awesome open source projects)

1. docbox

Markdown → JSON (Syntax Tree) using remark

Other awesome thing about docbox: robust tests for structure

2. retext-mapbox-standard

Takes advantage of retext + retext plugins + our own magic

acronyms

brand

forbidden

(another super special thanks to Katy Decorah for her excellent work on clear writing for everyone)

What it looks like in action:

Problem: the Static API is missing a JavaScript example

Solution: add a comment that says This API cannot be accessed with the JavaScript SDK

Part 2: Why our approach worked

Enforces consistency... automagically!

In content and in structure

mapping HTTP methods to verbs

In the documentation and the APIs

Ensures completeness... automagically!

Encourages and enables collaboration in writing documentation (not automagical)

Forces decisionmaking (also not automagical)

Super special bonus unintended awesome thing: more people able to speak knowledgeably about the product and ask compelling questions.

The truth: without automated testing, our documentation would fail.

Part 3: How you can do it too

No matter where you go, tests will follow you

copy-cop, which relies on plainlanguage.gov

Provides words to avoid, words to omit, words that can be swapped.

retext-mapbox-standard and docbox are both open source!

Other testing tools? Tweet them out with #writethedocs!