Documentation is critical to making a usable data platform. In surveys of users of the Mozilla Data Platform, the most common complaint has been lack of documentation. It is therefore important to expand and improve the documentation as often as possible.
- Bug reports
- Fixing minor problems
- Building the Documentation
- Adding a new article
- Supported Plugins
If you see an error in the documentation or want to extend a chapter, file a bug.
For smaller issues (for example, a typo or minor inaccuracy), it is not necessary to file a bug or even
check out the source.
Instead, use the
Edit on GitHub button on the bottom of any page, make your changes, and file a pull request entirely from the GitHub interface.
This documentation is stored as CommonMark Markdown in the
data-docs repository on GitHub.
To build a local copy, fork the repository and check out your copy. Then, see the README for up-to-date information on how to build the documentation.
You should read the style guide before adding a new article: it will help you write material that is more useful and fits cohesively into the rest of the documentation.
Be sure to link to your new article from
SUMMARY.md, 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.
Once you're happy with your contribution, open a pull request (PR). Give your PR a meaningful commit message
(see this article on commit message guidelines for some suggestions).
If there is a bug associated with your documentation, title it in the form of
Bug 1234 - <descriptive one-liner> - that way, the Bugzilla PR linker will pick up the PR and attach it to the bug.
After filing your PR, assign the appropriate person for review (GitHub will usually provide some suggestions), assuming you have permissions to do so yourself. If you do not have permission to assign a reviewer, see getting help.
You can insert a table of contents in any article by using the
toc shorthand. For example:
# My fine title
This article describes how to perform action X.
<!-- toc -->
## Section 1
## Section 2
For an example of what the rendered table of contents looks like, see the beginning of this article.
You can use
mermaid.js diagrams in code blocks. For example:
docs --> profit!
... is rendered as:
graph LR you -->|write|docs docs --> profit!
The documentation is hosted on Github Pages.
Updates to the documentation are automatically published to docs.telemetry.mozilla.org.