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:
Part one: The Mapbox API documentation story!
September 5, 2015
Good documentation pays attention to the small things:
Mapbox API Documentation 2: Document Harder
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
  1. Enforces consistency
  2. Ensures completness
  3. Pushes an eye toward correctness
  4. Makes it easier to contribute
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
mapbox-content-test
copy-cop, which relies on plainlanguage.gov
Provides words to avoid, words to omit, words that can be swapped.
Hemingway App
retext-mapbox-standard and docbox are both open source!
Other testing tools? Tweet them out with #writethedocs!
Thank you so much!