Tom MacWright

tom@macwright.com

Writing truthful documentation

Recently I was tasked with rewriting Mapbox’s REST API documentation. I learned a few things:

  1. Establish and enforce standards of factual reporting
  2. Make your job easier by fighting the war of magic numbers

Establish and enforce standards of factual reporting

There are three kinds of information you can use to write documentation:

  • Hearsay: taking somebody else’s word for it
  • History: using the old documentation
  • Code: reading the actual code for yourself

Hearsay falls victim to the chinese whispers: whoever you ask consults someone else, or their inconsistent memory, or confuses the current reality with a plan, and gives unreliable information.

History expects your old documentation to be correct. Unless documentation and development teams are working in perfect harmony, this isn’t a safe assumption.

Code is the only trustworthy source. Hearsay and history failed us time and time again until we established a standard of factual information: for an API behavior to be documented, it need to be cited with a link to the source code that makes it work.

Clone all of the repositories for all of the APIs you’re documenting, and read them. Code reading is underrated but awesome. Get an editor with good project-wide search and find the code you need to prove the docs you are writing.

We keep our code citations in a bibliography called TRUTH.md: it simply calls each section in our documentation and links directly to the code that proves its truth.

Make your job easier by fighting the war of magic numbers

The main things you want to confirm from code are specific names, locations, and numbers. Is the limit for the wibble-wobble API 10 or 20? Is its parameter called limit or count?

In our case, limits change more often than parameter names: we’re constantly increasing how large a file you can upload to Mapbox. But a typical API would put this limit within functional code, buried in the guts. We needed to cite several files for each limit.

This is a symptom of magic numbers. Yes, that’s a real programming term.

“Unique values with unexplained meaning or multiple occurrences which could (preferably) be replaced with named constants”

The gist is that you should name your constants and, in this case, keep them in an easily-found place. For our server code, this means in a file called lib/constants.js, and everything in the file is connected to documentation.

By isolating these values, we can also add a neat header at the top of the file - here’s what it is:

/**
 * Rate limit constants for the geocoding service. This module
 * is the reference. Coordinate with
 * the documentation and sales team before changing these values.
 */

It’s not a silver bullet, but changing our server code to draw a clear line around user-facing values helps us coordinate changes between development and documentation.


  • Documentation should cite code & use a bibliography
  • Code should be documentable by separating constants from logic