Contributing

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

If you see an error in the documentation or want to extend a chapter, file a bug.

Fixing minor problems

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.

Building the Documentation

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.

Adding a new article

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.

Review

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.

Supported Plugins

Table of contents

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.

Mermaid

You can use mermaid.js diagrams in code blocks. For example:

```mermaid
graph LR
  you -->|write|docs
  docs --> profit!
```

... is rendered as:

graph LR
  you -->|write|docs
  docs --> profit!

Publishing

The documentation is hosted on Github Pages.

Updates to the documentation are automatically published to docs.telemetry.mozilla.org.