Testing: it's not just for code anymore!
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
How we did it: docbox and retext-mapbox-standard
(special thanks to tmcw
for contributing to awesome
open source projects)
Markdown → JSON (Syntax Tree) using remark
Other awesome thing about docbox: robust tests for structure
Takes advantage of retext
+ retext plugins
+ our own magic
What it looks like in action:
Part 2: Why our approach worked
- Enforces consistency
- Ensures completness
- Pushes an eye toward correctness
- 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
Provides words to avoid, words to omit, words that can be swapped.
Other testing tools? Tweet them out with #writethedocs!