Documentation is critical to making a usable data platform. When surveying our users, their most common complain has been our lack of documentation. It's important that we improve our documentation as often as possible.
The documentation is intended to be read as HTML at docs.telemetry.mozilla.org. 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.
npm install gitbook-cli -g
and install the gitbook plugins with:
You can then serve the documentation locally with:
The complete documentation for the gitbook toolchain is at: https://toolchain.gitbook.com/. If you run into any technical limitations, let me (@harterrt) know. I'm happy to change the tooling to make it as much fun as possible to write.
Be sure to link to your new article from
SUMMARY.md, or GitBook will not render the file.
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.
Limit lines to 100 characters where possible. Try to split lines at the end of sentences. 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.
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.
This script depends on ghp-import.
Keep in mind that this will deploy the docs to your
If you're working from a fork (which you should be),
deploy.sh 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.