Documentation is critical to making a usable data platform. When surveying our users, their most common complaint has been our lack of documentation. It's important that we improve our documentation as often as possible.

Bug reports

If you see an error in the documentation or want to extend a chapter, please file a bug.

Getting the Raw Documentation

The documentation is intended to be read as HTML at However, we store the documentation in raw text files in the firefox-data-docs repo. To begin contributing to the docs, fork the firefox-data-docs repo.

Building the Documentation

The documentation is rendered with mdBook.

To build the documentation locally, you'll need additional preprocessors:

Download releases for your system, unpack it and place the binary in a directory of your $PATH.

If you have rustc already installed, you can install a pre-compiled binary directly:

curl -LSfs | sh -s -- --git badboy/mdbook-toc
curl -LSfs | sh -s -- --git badboy/mdbook-mermaid
curl -LSfs | sh -s -- --git badboy/mdbook-open-on-gh

This will place mdbook-toc and mdbook-mermaid into ~/.cargo/bin. Make sure this directory is in your $PATH or copy it to a directory of your $PATH.

You can also build and install the preprocessors:

cargo install mdbook-toc
cargo install mdbook-mermaid
cargo install mdbook-open-on-gh

You can then serve the documentation locally with:

mdbook serve

The complete documentation for the mdBook toolchain is available online at If you run into any technical limitations, let @harterrt or @badboy know. We are happy to change the tooling to make it as much fun as possible to write.

Adding a new article

Be sure to link to your new article from, or mdBook will not render the file.

The structure of the repository is outlined in this article.

This documentation is under active development, so we may already be working on the documentation you need. Take a look at this bug component to check.

Style Guide

Articles should be written in Markdown. mdBook uses the CommonMark dialect.

Limit lines to 100 characters where possible. Try to split lines at the end of sentences, or use Semantic Line Breaks. This makes it easier to reorganize your thoughts later.

This documentation is meant to be read digitally. Keep in mind that people read digital content much differently than other media. Specifically, readers are going to skim your writing, so make it easy to identify important information.

Use visual markup like bold text, code blocks, and section headers. Avoid long paragraphs. Short paragraphs that describe one concept each makes finding important information easier.

Spell checking

Articles should use proper spelling, and pull requests will be automatically checked for spelling errors.

Technical articles often contain words that are not recognized by common dictionaries, if this happens you may either put specialized terms in code blocks, or you may add an exception to the .spelling file in the code repository.

For things like dataset names or field names, code blocks should be preferred. Things like project names or common technical terms should be added to the .spelling file.

To run the spell checker locally, install the markdown-spellcheck library, then run the scripts/ script from the root of the repository.

You may also remove the --report parameter to begin an interactive fixing session. In this case, it is highly recommended to also add the --no-suggestions parameter, which greatly speeds things up.

Link checking

Any web links should be valid. A dead link might not be your fault, but you will earn a lot of good karma by fixing a dead link!

To run the link checker locally, install the markdown-link-check library, then run the scripts/ script from the root of the repository.

Supported Plugins


You may use mermaid.js diagrams in code blocks:

graph LR
  you -->|write|docs
  docs --> profit!

Which will be rendered as:

graph LR
  you -->|write|docs
  docs --> profit!


Once you're happy with your contribution, please open a PR and flag @harterrt for review. Please squash your changes into meaningful commits and follow these commit message guidelines.


The documentation is hosted on Github Pages.

Updates to the documentation are automatically published to when changes are merged.

To publish to your own fork of this repo, changes need to be pushed manually. Use the deploy script to publish new changes.

This script depends on ghp-import.

Keep in mind that this will deploy the docs to your origin repo. If you're working from a fork (which you should be), will update the docs hosted from your fork - not the production docs.


This document's structure is heavily influenced by Django's Documentation Style Guide.

You can find more context for this document in this blog post.