Mattermost Handbook
Need help?How to spend company moneyHow to update the HandbookRelease overview
0.2.1
0.2.1
  • Mattermost Handbook
  • Company
    • About Mattermost
      • List of terms
      • Business model
      • Mindsets
    • "How to" guides for staff
      • How to set up a 1-1 channel
      • How to update the handbook
      • How to manage Handbook notifications
      • How to change mobile device
        • How to handle a lost mobile device
      • How to do a mini-retrospective
      • How to autolink keywords in Mattermost
  • Operations
    • Company operations
      • Areas of Responsibility
      • Mattermost Leadership Team (MLT)
        • MLT cadence
      • Company measures
        • Metrics definitions
        • FY23 goals board
        • MLT metrics
      • Company cadence
      • Company policies
        • Community response policy
        • Security policy
      • Company processes
        • Issue/solution process
        • Company agreements
        • Publishing
          • Public web properties
          • Publishing guidelines
            • Brand and visual design guidelines
            • Voice, tone, and writing style guidelines
              • Contribute to documentation
            • Confidentiality guidelines
          • Post-publication quality control process
      • Handbook processes and policies
        • Handbook onboarding
      • Fiscal year planning
    • Research and Development
      • Organization
        • Tech Writing
        • Data engineering
        • Delivery
        • Cloud Platform
        • Site Reliability Engineering
        • GRC
        • Product Security
        • Security Operations
      • Processes
        • Feature Labels
      • Product
        • Product planning
          • Product philosophy and principles
          • Prioritization process
          • Release planning process
          • Roadmap views
          • Release plan
          • Launch plan
          • Feature requests
        • Development process
          • Mobile feature guidelines
          • Deprecation policy
          • Mattermost software requirements process
          • Jira ticket lifecycle
          • Creating new Jira bug tickets
            • Priority levels for tickets
            • Jira fix versions
        • Release process
          • Release overview
          • Feature release process
          • Dot release process
          • Security release process
          • Mobile app release process
          • Desktop app release process
          • Release tips
          • Release scorecard definitions
        • How-to guides for Product
          • How to use productboard
          • How to record a roadmap video
          • How to update integrations directory
          • How to write a feature release announcement
        • Product Management team handbook
          • Product Management Areas of Ownership
          • Product Manager onboarding
          • Product Manager levels
          • Professional development
        • Product Design team handbook
          • Product Design levels
        • Technical Writing team handbook
          • Work with us
          • User interface text guidelines
          • Documentation style guide
          • Our terminology
          • Guidelines for PMs and developers
          • Guidelines for community contributions
          • Technical Writer levels
          • Docathon 2021
            • Getting started with contributing
        • Growth
          • A/B testing methodology
          • PQL definition
        • Analytics
          • Product Analyst Engineer levels
          • Looker
            • Dashboards
            • Explores
          • Telemetry
        • Developer relations
        • Product team hangouts
      • Engineering
        • Infrastructure engineering
          • Cloud infrastructure cost KPIs
          • Cloud data export process
          • Cloud churn process
          • Reliability Manifesto
          • Production Readiness Review
          • Infrastructure Library
        • Integrations team processes
        • Plugin release process
        • Data Engineering
        • Sustained Engineering
          • On call
        • How to go to a conference
        • Public speaking
        • Core contributor expanded access policy
      • Quality Assurance
        • QA workflow
        • QA testing tips and tools
        • Rainforest process
    • Messaging and Math
      • How-to guides for M&M
        • How to create release announcements
        • How to create screenshots and GIFs
        • How to write Mattermost case studies
        • How to write guest blog posts for Mattermost apps and services
        • How to write Mattermost recipes
        • How to compose tweets
        • How to create a split test for web page
        • How to run meetups
        • How to run executive dinners
      • Checklists for M&M
        • Blog post checklist
        • Bio checklist
      • Mattermost websites
      • Demand generation reporting
      • M&M Asana guidelines
      • Content marketing
        • How to use the editorial calendar
        • Content development and distribution
        • Video content guidelines
        • How to contribute content
    • Sales
      • Deal Desk
      • Partner programs
      • Lead management
    • Deployment Engineering
      • Overview
      • Workflows
      • Frequently Asked Questions
      • Playbook for MME Sev 1 Outages
      • Status Update Template
    • Program Management
    • Customer Success
      • Customer Support
    • Legal
      • Contracts
      • Ironclad Basics
        • Company-Wide Workflows
        • Sales Contracts and Workflows
        • Signing a Contract and Contract Repository
    • Finance
      • Budget
      • How to use Airbase
        • Access Airbase
        • Navigate Airbase
        • How to submit a purchase request
        • How to submit a reimbursement request
        • How to review a reimbursement request
        • Vendor portal guide
        • Frequently asked questions
      • Onboarding
        • Vendor onboarding
        • ROW staff onboarding
      • Staff member expenses
        • How to spend company money
        • How to spend company money: Internships
        • Corporate credit card policy
        • How to access Airbase
        • Gifting policy
        • How to book airfare and travel
        • How to reimburse the company
        • How to convert currencies
        • How to get paid
      • Arrange a Bounty Program
      • Naming files and agreements
      • Risk management
        • Mattermost U.S. consulting agreements
      • Operations playbook
    • Security
      • Policies
      • Privacy
        • Data deletion requests
        • Data subject access requests
      • Product Security
        • Product Vulnerability Process
        • Working on security-sensitive pull requests
        • Secure Software Development guide
      • Security Operations
        • User guides
    • Workplace
      • PeopleOps
        • HR cadences
        • HR systems
        • HR Processes
        • Working at Mattermost
          • Onboarding
            • Things everyone must know
            • Staff onboarding
            • Engineer onboarding timeline and expectations
            • Manager onboarding
            • Frequently asked questions
          • Learning and development
          • Mattermost communication best practices
          • Paid time off
            • Out of office email example
          • Travel
            • Business travel insurance
          • Leaves of absence
            • Pregnancy leave
            • Baby bonding parental leave
            • Jury duty
          • Workplace program
          • Relocation
          • Total rewards
        • Performance reviews
          • Formal review process
          • New staff performance review
          • Informal review process
        • Transfers and promotions
        • Offboarding instructions for managers
        • People compliance
      • People policies
      • Groups
        • Staff Resource Groups
      • Approvals and iteration
      • IT
        • IT helpdesk
        • Hardware and software purchases
        • Hardware buy back policy
        • Software systems
  • Contributors
    • Contributors
      • Equity, diversity, and inclusion
      • How to contribute to Mattermost
        • Community Content program
        • Documentation contributions
        • Help Wanted tickets
        • Localization
        • Contribution events
      • Mattermost community
      • Contributor kindness
      • Community systems
      • Guidelines and playbooks
        • Social engagement guidelines
        • Contribution guidelines and code of conduct
        • Mattermost Community playbook
        • How to run a Hackathon
        • Hacktoberfest event organizer guide for Mattermost
    • MatterCon
      • Staff information privacy management
      • Mattermost events code of conduct
      • MatterCon2021
    • Join us
      • Ice-breakers
      • Help Wanted tickets
      • Localization
      • Mattermost GitHub sponsorship
      • Things candidates should know
      • Staff recruiting
      • Recruiting cadences
        • Product Manager hiring process
      • Exec recruiting
        • EA logistics
  • Help and support
    • Contact us
Powered by GitBook
On this page
  • Who can update the Handbook?
  • How do I know what to update?
  • Hints and tips
  • Your first Mattermost contribution
  • Edit an existing page
  • Edit a page directly
  • Edit a file in the repo
  • Create a new page
  • Create a new section
  • Frequently asked questions
  • How do I format a page?
  • How do I update the left-hand navigation?
  • How do I add an image to the documentation?
  • Can I convert a Google Doc to Markdown?
  • Training video
  • Official Handbook reviewers

Was this helpful?

Edit on Git
Export as PDF
  1. Company
  2. "How to" guides for staff

How to update the handbook

PreviousHow to set up a 1-1 channelNextHow to manage Handbook notifications

Last updated 1 year ago

Was this helpful?

On this page

Who can update the Handbook?

Contributions from everyone are welcome, including staff members and community members. You don't have to work at Mattermost to submit an update or fix something that's caught your eye.

How do I know what to update?

"Update the Handbook" is a term we use regularly at Mattermost but it's not always obvious exactly what to update or how. Here are some examples of what a Handbook update could be:

  • Updating your team page with new team members and AORs.

  • Adding a new page to describe a new process.

  • Updating existing content to accommodate a change in process, policy, or requirement.

  • Archiving old content that should be preserved for reference.

Updating the Handbook can be as easy as fixing a typo, or as complex as reorganizing an entire section. The key is to update it regularly, so that updates are less daunting and time-consuming.

Hints and tips

The Handbook is a public-facing body of work and although it's a constantly-evolving work-in-progress, we still need to ensure our content is accurate, easy to read, and clear.

  • Be concise: Say what's essential, not more.

  • Don't aim for perfection: Our goal is regular iteration, so your content doesn't have to be perfect before it's published. It will be reviewed by an editor prior to publication so any major errors will be addressed then.

Your first Mattermost contribution

Now you're ready to get started.

Edit an existing page

Once a page is edited and you're happy with the changes, it's submitted as a pull request which is then reviewed. If there's any feedback or comments have been made, you'll be alerted. If suggestions have been made, you can choose to commit them (add them to your content) or you can ask the reviewer for more information before doing that.

When the PR is approved, it'll be merged and published. If you have more changes to make, you can simply repeat the process.

Edit a page directly

This is probably the quickest way to make changes, as it doesn't require you to find the file in the repo first.

  1. Login to your Mattermost GitHub account

  2. Open the Handbook and navigate to the page you want to edit.

  3. Underneath the blue banner, locate three dots next to the page title at the top of the page. Click on the three dots and choose Edit on GitHub. This action will open the page in GitHub.

  4. In GitHub select the pencil icon in the navigation bar (above the page header) called Edit this file to open the editable Markdown-format page. If you see Edit this file in your fork of this project the process is the same, it just means you're not part of the Mattermost organization and are working in a forked repo.

  5. Make your edits. When you're ready to submit your changes, commit your changes to start a pull request.

  6. Add a descriptive title if the default title isn't sufficient. Add an extended description to summarize the changes you've made.

  7. The default setting is Create a new branch for this commit and start a pull request. In the field below that, you can customize the branch name - you can also leave it as default.

  8. Select Propose changes.

  9. On the next page, you can scroll down to compare changes with the original document to double-check your changes.

  10. If you're happy with them 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.

Edit a file in the repo

This option works best if you know where the file is located in the repo.

  1. Navigate through the directories to the file you want to edit.

  2. Once you've found the file, select Edit this file in the top corner. If you see Edit this file in your fork of this project the process is the same, it just means you're not part of the Mattermost organization and are working in a forked repo.

  3. Make your edits. When you're ready to submit your changes, commit your changes to start a pull request.

  4. Add a descriptive title if the default title isn't sufficient. Add an extended description to summarize the changes you've made.

  5. The default setting is Create a new branch for this commit and start a pull request. In the field below that, you can customize the branch name - you can also leave it as default.

  6. Select Propose changes.

  7. On the next page, you can scroll down to compare changes with the original document to double-check your changes.

  8. If you're happy with them confirm that the title and description are correct, then select Create pull request.

Create a new page

  1. Navigate through the directories until you reach the section where you'd like to add your new content.

  2. Select Add file > Create new file.

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.

  1. Write your content as needed.

  2. When you're ready to submit your changes, commit your changes to start a pull request.

  3. Add a descriptive title if the default title isn't sufficient. Add an extended description to summarize the changes you've made.

  4. The default setting is Create a new branch for this commit and start a pull request. In the field below that, you can customize the branch name - you can also leave it as default.

  5. Select Propose changes.

  6. On the next page, you can scroll down to compare changes with the original document to double-check your changes.

  7. If you're happy with them confirm that the title and description are correct, then select Create pull request.

Create a new section

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. Select Add file > Create 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. When you're ready to submit your changes, commit your changes to start a pull request.

  6. Add a descriptive title if the default title isn't sufficient. Add an extended description to summarize the changes you've made.

  7. The default setting is Create a new branch for this commit and start a pull request. In the field below that, you can customize the branch name - you can also leave it as default.

  8. Select Propose changes.

  9. On the next page, you can scroll down to compare changes with the original document to double-check your changes.

  10. If you're happy with them confirm that the title and description are correct, then select Create pull request.

Frequently asked questions

How do I format a page?

How do I update the left-hand navigation?

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 @carrie.warner in Mattermost (@jasonblais or @cwarnermm in GitHub) for assistance if needed.

How do I add an image to the documentation?

Follow these two steps:

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

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

Can I convert a Google Doc to Markdown?

Once the add-on is installed, there are a number of conversion settings you can configure. Selecting all but the Use HTML headings/IDs option is recommended.

  • To see the embedded errors and warnings, disable the Use reckless mode option.

  • To see all conversion details, disable the Suppress info comment option.

The resulting Markdown code isn't perfect, but it's an excellent initial step towards preparing a PR for the Mattermost Handbook. Review the following areas of converted code:

  • Embedded images must be saved out as files, added to appropriate image folders, and links need to be added to point to correct locations.

    • If the doc contains screenshots or other image assets, right-click on the embedded image in the Google Doc, then select Save to Keep.

    • In the right pane, right-click on the image in the Keep list, then select Save Image As. Rename the image file as needed to match the Markdown code.

  • Images need to live in the .gitbook/assets folder and must use a relative link in the source file.

  • Numbered lists and nested lists likely need corrections.

  • Many lines end in a / which need to be removed.

  • ALT tags are added as alt_text for all images. Update the ALT tag to be more descriptive, or remove it altogether.

Training video

Official Handbook reviewers

Below is a list of approved reviewers.

  1. @cwarnermm: Reviews major changes to handbook.mattermost.com, such as updates to the Table of Contents (SUMMARY.md).

  2. @cwarnermm: Editor reviews of all submitted PRs for correct grammar and consistent style.

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, @amyblais, @cwarnermm: Write permissions to the repository.

  2. Staff contributors: Submit changes to handbook.mattermost.com using PRs. May 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 using PRs. Do not have access to request reviews, add labels. Can submit PR reviews.

Get feedback: Have someone from your target audience read your draft to share feedback so you can .

If this is your first time contributing to Mattermost, first read the and sign it (at the bottom of the page), so you can be added to the Mattermost . Please ensure the GitHub username field matches your GitHub username exactly, including capitalization.

If you're not already a member of the mattermost GitHub organization, you can request access through the . This will allow you to edit the files in the Handbook repo without having to create a fork for your changes.

When you edit an existing page, it's usually to add content, remove content, or edit existing content. In general it's easiest if pages are edited directly, although you're also welcome to if that's easier for you.

All editing is done in GitHub, as that's where the Handbook files are stored. Pages are formatted using Markdown - if you're not familiar with Markdown, you can take a look at for tips. Don't worry too much about formatting - it can always be adjusted during the review process.

To learn more about Markdown formatting, see the , or .

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 for more details.

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

Open the .

To learn more about Markdown formatting, see the , or .

Creating new content can take the form of a new page, or . Some things to keep in mind are naming conventions and that the Table of Contents entry is made manually in the SUMMARY.md file.

Open the .

Add your new page to the . If you plan to reorder the table of contents as part of your change, please tag @jason.blais or @carrie.warner in Mattermost (@jasonblais or @cwarnermm in GitHub) as a redirect may need to be set up to accommodate the change.

.

Add your new section to the . If you plan to reorder the table of contents as part of your change, please tag @jason.blais or @carrie.warner in Mattermost (@jasonblais or @cwarnermm in GitHub) as a redirect may need to be set up to accommodate the change.

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 , or .

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

Go to the folder, select 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.

Yes! Sometimes it's easier to draft content for the Handbook in a Google Doc. An open-source Google Drive add-on called can convert the content to Markdown. See the add-on for details on installing and using this tool.

.

@kevinfayle: Signs off on changes to .

@aedott: Signs off on changes to .

@it33: Signs off on changes to .

@natalie-hub: Signs off on changes to .

@it33: Signs off on changes to signing authority ().

@dschalla: Signs off on changes to .

Mattermost Contributor Agreement
Approved Contributor List
Mattermost IT helpdesk
this page
Mattermost guide for formatting text
the guide from GitBook
Commenting on pull requests
https://handbook.mattermost.com
Handbook repo
Mattermost guide for formatting text
the guide from GitBook
an entirely new section
Handbook repo
Handbook table of contents
Watch a two-minute training video on how to create a new page in GitHub
Handbook table of contents
Mattermost guide for formatting text
the guide from GitBook
SUMMARY.md
/assets
Docs to Markdown
documentation
Watch a training video on how to update the handbook in GitHub
marketing ops and analytics
messaging and math
finance
workplace
example
Security
Who can update the Handbook?
How do I know what to update?
Hints and tips
Your first Mattermost contribution
Edit an existing page
Create a new page
Create a new section
Frequently asked questions
Training video
Official Handbook reviewers
edit files directly from the repo
savor surprises