Mozilla Data Documentation
This document is intended to help Mozilla's developers and data scientists analyze and interpret the data gathered by the Firefox Telemetry system.
To learn more about what data Firefox collects and the choices you can make as a user, please see the Firefox Privacy Notice.
The rendered documentation is hosted at https://docs.telemetry.mozilla.org/.
Building the Documentation
The documentation is rendered with mdBook. We use a fork named mdbook-dtmo that includes a number of custom additions to mdbook for our environment (for example, a plugin to automatically generate a table-of-contents).
You can download
mdbook-dtmo on the GitHub releases page.
Please use the latest version.
Unpack it and place the binary in a directory of your
If you have rustc already installed, you can install a pre-compiled binary directly:
curl -LSfs https://japaric.github.io/trust/install.sh | sh -s -- --git badboy/mdbook-dtmo
Make sure this directory is in your
$PATH or copy it to a directory of your
You can also build and install the preprocessors:
cargo install mdbook-dtmo
You can then serve the documentation locally with:
The complete documentation for the mdBook toolchain is available online at https://rust-lang.github.io/mdBook/. If you run into any problems, please let us know. We are happy to change the tooling to make it as much fun as possible to write.
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
.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
The markdown-spell-check package checks spelling as part of the build process. To run it locally, install node.js (if not already installed) and run
npm install at the root of the repository. Then run the
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.
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!
The markdown-link-check package checks links as part of the build process. Note that dead links do not fail the build: links often go dead for all sorts of reasons, and making it a required check constantly caused otherwise-fine pull requests to appear broken. Still, you should check the status of this check yourself when submitting a pull request: you can do this by looking at the Travis CI status after submitting it.
To run link checking locally, run the installation steps described for spell checking if you haven't already, then run the
We use prettier to ensure a consistent formatting style in our markdown. To reduce friction, this is not a required check but running it on the files you're modifying before submission is highly appreciated! Most editors can be configured to run prettier automatically, see for example the Prettier Plugin for VSCode.
To run prettier locally on the entire repository, run the installation steps
described for spell checking if you haven't already, then
See contributing for detailed information on making changes to the documentation.