Help Improve Mattermost Documentation

While reading the Mattermost documentation, you might find something that can be improved. Perhaps an ambiguous phrase, a broken link, or a spelling error, or something that doesn’t fit with the Mattermost Documentation Guidelines.

When you come across an opportunity like this, we’d highly appreciate your help improving the Mattermost documentation. You can offer an edit of the documentation with just a few straight forward steps:

1) If you don’t have one already, sign-up for a free GitHub account at http://github.com.

This account is used to write proposals for changes to the Mattermost documentation in something called a “pull request”. It’s a proposed change to the documentation to be reviewed by its author to decide whether or not it should be accepted (and every reasonable one will be accepted).

2) Find an issue that clearly needs correcting

Most likely you found an issue while trying to install or configure Mattermost–alternatively, if you’re just practicing, you can go to the Mattermost documentation site and look through the materials until you find something that could be clearly improved.

Example below of an error in the systems requirements document, where “30 person team” needs a hyphen to make it correct as “30-person team”.

After finding something, look in the GitHub repository to find the corresponding page. For example, if I wanted to change something on http://docs.mattermost.com/help/settings/account-settings.html, I would go to GitHub and click into Help > Settings > Account Settings to get to the page.

3) Click the “Edit this file” button on the page

It’s the one that looks like a pencil:

You can use the “Preview Changes” tab to see how the change looks.

4) Under “Commit changes” area concisely explain your proposed change

Then click “Create new branch for this commit and start a pull request” and then “Propose new pull request” then “Create pull request” and you’re request will have been submitted.

5) Complete the Contributor License Agreement, if you haven’t already

This is standard paperwork to provide the open source project the right to use your “work”. Detailed information is available from the link above.

Once you’ve completed the form your GitHub username will appear on a list of approved contributors, which will allow your pull request to be reviewed and accepted by the team.

BONUS: If you’re among the first 100 contributors to the Mattermost project and you included a mailing address in the form above, you’ll receive Limited Edition Mattermost Mug as a thank you gift in the mail.

6) (not used all the time) Responding to reviewer feedback

If you’ve submitted a pull request to update documentation and a reviewer found an error (most commonly a typo), you can easily make a correction by clicking on “Files changed” then the “Change this file using the online editor” button (it looks like a pencil).

When your correction is complete–similar to Step 4–enter a short note of your change in the “Commit changes” section (something like “Fixed typo” if the reviewer found a typo) and click the “Commit changes” button with “Commit directly to the branch” option selected by default to save your changes back into your pull request.

The reviewer will receive an alert to re-review the pull request so it can be accepted.

If I make a change that affects 30 files, should I lump all of them into one Git commit and one PR? Or is it better to do one PR for each file? Will having that many files in one commit cause difficulties when merging?

I’m thinking of going through the .rst files and adjusting the title underlines to be at least as long as the title text. This would bring them into conformance with the reStructuredText spec and reduce the number of warnings in the build by about 160.

1 Like

Thanks for the question and for the help!

So long as a reviewer can read the diffs, okay for one PR. There’s some limit where GitHub no longer lets you read the diffs, so not sure what the limit is though…

You might need to rebase if there are PRs ahead of you that touch the same file, as those would typically get merged ahead of yours.

That’s awesome @JeffSchering!

Ok, no problem.

As a way of learning Go I plan to write a program to iterate over the .rst files and adjust them if needed. Because I have a few things on the go right now, I have less than an hour a day for this so it might be a while before the PR comes in.

Holy Go Batman! I naively thought that writing the script in Go would be a simple matter of learning some new syntax. But because Go is also a different way of doing things, it’s taking a bit longer than I expected.