bibbu994 / data-docs

A guide for Mozilla's developers and data scientists to analyze and interpret the data gathered by our data collection systems.

Mozilla Data Documentation

This documentation was written to help Mozillians analyze and interpret data collected by our products, such as Firefox and Mozilla VPN.

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/.

Issues for this documentation are tracked in Bugzilla (file a bug).

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 $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-dtmo

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-dtmo

You 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.

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.

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/spell_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.

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!

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.

Markdown formatting

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 run the scripts/prettier_fix.sh script.

Contributing

See contributing for detailed information on making changes to the documentation.