Testing: it's not just for code anymore
summary
Mapbox builds an automated content testing system using docbox and retext-mapbox-standard to enforce structure, language, and examples; tests fail builds when a method lacks a JavaScript example or uses forbidden phrasing. The repo shows 43 contributors editing docs and 49 testing-related projects, proving the system scales. It catches brand and style errors, enforces required examples per language, reduces manual editing, and is fully open source so teams can copy the exact tools and scripts that actually work.
AI-written summary · about
chapters (16)
- 0:00Intro
- 0:35this talk: testing is good.
- 1:18Part one: The Mapbox API documentation story!
- 6:42Markdown → JSON (Syntax Tree) using remark
- 9:29Other awesome thing about docbox: robust tests for structure
- 10:022. retext- mapbox- standard
- 13:33What it looks like in action
- 15:521. Enforces consistency 2. Ensures completness 3. Pushes an eye toward correctness 4. Makes it easier to contribute
- 16:12Enforces consistency... pical automagically!
- 16:44In the documentation API and the APIs
- 17:37Encourages and enables collaboration in writing documentation (not automagical)
- 18:47Super special bonus unintended awesome thing: more people able to speak knowledgeably about the product and ask compelling questions.
- 20:03The truth: without automated testing, our documentation would fail.
- 21:01Part 3: How you can do it too
- 22:57Hemingway App
- 23:15retext-mapbox- standard and docbox are both open source!
related talks
49mUnit Test the Docs: Why You Should Test Your Code Examples
38mDocs as Tests: A Strategy for Resilient Docs
47mEngineering Documentation
44mTesting Documentation: Why So Technical?
21mMake a map in minutes: How Mapbox is streamlining map development
35mBuilding Docs like Code: Continuous Integration for Documentation
24mTested & Correct: How to Make Sure Your Documentation Keeps Working
37mKeeping trust: Testing documentation as part of a continuous integration process