This document is intended to help Mozilla's developers and data scientists analyze and interpret the data gathered by the Firefox Telemetry system.
At Mozilla, our data-gathering and data-handling practices are anchored in our Data Privacy Principles and elaborated in the Mozilla Privacy Policy.
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/.
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 $PATH.
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-dtmoMake 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-dtmoYou can then serve the documentation locally with:
mdbook-dtmo serve
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
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.
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 scripts/link_check.sh script.
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 scripts/link_check.sh script.
See contributing for detailed information on making changes to the documentation.