Skip to content

Latest commit

 

History

History
120 lines (73 loc) · 8.18 KB

how-to-update-handbook.md

File metadata and controls

120 lines (73 loc) · 8.18 KB

How to Update the Handbook

Guidelines

  • Be concise: Say what's essential, not more.
  • Get feedback: Have someone from your target audience read your draft to share feedback so you can savor surprises.

Steps

If this is your first time contributing to Mattermost, first read the Mattermost Contributor Agreement and sign it (at the bottom of the page), so you can be added to the Mattermost Approved Contributor List. Please ensure the GitHub username field matches your GitHub username exactly, including capitalization. Next, please request access to the Mattermost organization DevOps Team Channel.

Editing an existing page

  1. The quickest way to begin is navigating to the page you want to edit in Mattermost Handbook, then clicking the Edit on GitHub icon in the top right navigation. This opens the page in GitHub that you can edit.
  2. In GitHub click the pencil icon in the navigation bar (above the page header) called Edit the file in your fork of this project to open the editable Markdown-format page.
  1. Make your edits. When you're ready to submit your changes, scroll to the bottom of the page to commit your changes and start a pull request.
  2. Add a descriptive title if the default title isn't sufficient. Add an extended description to summarize the changes you've made.
  3. Click the Propose file change button.

  1. On the next page, scroll down to compare changes with the original document and then select Create pull request.
  2. Confirm that the title and description are correct. Then select Create pull request.

Once a pull request has been submitted, a core committer with write-access assigns relevant reviewers and labels to kick off the review process. The review process includes aligning the content with the Style Guide, validating the changes, and tagging any other relevant committers.

Multiple committers may comment on your pull request and provide edits or suggestions which you can commit directly. You can also add line comments. Take a look at Commenting on pull requests for more details.

Once the review process is complete, the change is merged and pushed live. We recommend that you review your changes at https://handbook.mattermost.com for potential formatting errors.

Creating a new page

Creating a new page follows the same process as above, with two exceptions:

  • Navigate to that section of the handbook where you'd like to add the new page and select Create new file.
  • Add your new page to the Handbook table of contents. If you plan to reorder the table of contents as part of your change, please tag @jason.blais or @justine.geffen in Mattermost (@jasonblais or @justinegeffen in GitHub) as a redirect may need to be set up to accommodate the change.

Watch a two-minute training video on how to create a new page in GitHub.

Creating a new folder

If you want to create nested content, you can create folders. You cannot create an empty folder and then add files to that folder, but rather creation of a folder must happen together with adding of at least a single file. On GitHub you can do it this way:

  1. Navigate to the folder within which you're creating your new folder.
  2. Click on New file.
  3. Enter the new folder's name in the text field and add / at the end.
  4. In the next text box, enter the name of the new page, ending with .md.
  5. Select Commit new file.
  6. Add a descriptive title if the default title isn't sufficient. Add an extended description to summarize the changes you've made.
  7. Click the Propose file change button.

Folder and page naming conventions

When you create a new page in the handbook ensure that:

  • The page name is all lowercase.
  • There are hyphens instead of spaces between the words.
  • New page names end with .md.

Note: Folder names do not end with .md.

Frequently Asked Questions

How do I format a page?

All Handbook pages are written in Markdown, which is also the language used to post messages in Mattermost. To learn more about Markdown formatting, see the Mattermost guide for formatting text, or the guide from GitBook.

How do I update the left-hand navigation?

You can update the left-hand navigation in the SUMMARY.md file.

Important note:

GitBook dynamically changes the URL based on the location in the table of contents. This means that when a page changes its location, the previous link results in a 'page not found' error.

There is a redirect file that we use to prevent this in the gitbook.yaml file. Please mention @jason.blais or @justine.geffen in Mattermost (@jasonblais or @justinegeffen in GitHub) for assistance if needed.

How do I add an image to the documentation?

Follow these two steps:

  • Go to the /assets folder, click Upload files, then upload the image files you want to add to your documentation. Make sure to have a clear name for each file you upload.

  • Next, go to the section you want to add an image to and include the following Markdown formatting:

    ![](../../../.gitbook/assets/release-timeline-jan2020.png)

Training video

Watch a training video on how to update the handbook in GitHub.

Approved reviewers and permissions

Below is a list of approved reviewers.

  1. @jasonblais: Reviews major changes to handbook.mattermost.com, such as updates to the Table of Contents (SUMMARY.md).
  2. @justinegeffen, @amyblais, @cwarnermm: Editor reviews of all submitted PRs for correct grammar and consistent style.
  3. @kevinfayle: Signs off on changes to marketing ops and analytics.
  4. @aedott: Signs off on changes to messaging and math.
  5. @TQuock: Signs off on changes to finance.
  6. @natalie-hub: Signs off on changes to workplace.
  7. @it33: Signs off on changes to signing authority (example).

Each PR should be reviewed by at least one approved reviewer. A build check requiring at least one approved review prior to a merge is planned, similar to other Mattermost repositories.

Below is a list of permissions handbook contributors have access to:

  1. @jasonblais, @justinegeffen, @amyblais, @cwarnermm: Write permissions to the repository.
  2. Staff contributors: Submit changes to handbook.mattermost.com via PRs. Have access to request reviews, add labels, submit PR reviews, and be requested as reviewers.
  3. Non-staff contributors: Submit changes to handbook.mattermost.com via PRs. Have access to request reviews, add labels, and submit PR reviews.