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
  • Submitting feature documentation
  • Feature documentation MVP (Product Managers)
  • Add reviewers to PRs
  • Providing editorial feedback

Was this helpful?

Edit on Git
Export as PDF
  1. Operations
  2. Research and Development
  3. Product
  4. Technical Writing team handbook

Guidelines for PMs and developers

PreviousOur terminologyNextGuidelines for community contributions

Last updated 6 months ago

Was this helpful?

Submitting feature documentation

Feature documentation is a joint effort between Product Managers, Developers, and Technical Writers. In the same way that we want to empower everyone to contribute to our documentation, Product Managers are encouraged to write MVP documentation for their product/feature.

Feature changes and new features first exist as code PRs. These PRs form the basis of whatever changes are being documented. If a code PR is for a new feature, major update to an existing feature, or a fix that impacts the current documentation, it's recommended that a documentation update is made. The Technical Writers work closely with their development teams to ensure that these types of changes are documented accordingly.

One way we do this is by using the Docs/Needed label. When a code PR is submitted, that may have documentation impact, the Docs/Needed label is added. The assigned writer then reviews the PR and, if there are documentation changes needed, opens a PR in the docs repo with reference to the code PR.

As a developer you are also welcome to update the documentation yourself in one of the following ways:

  • Update the relevant page on , and submit a PR for that. This PR is submitted to the docs repo, reviewed by the relevant team members, and merged from there.

  • Submit your documentation as a new file, including the context and changes, any code samples, and processes. You can submit this as part of your code PR, or you can open a new PR in the docs repo and include a link to your open code PR.

We don't expect a huge body of documentation or that it's perfectly-written - but rather a clear, concise outline of the change which can be added to our documentation. The content can be provided as a list, rough notes, or you can use the example below for content and structural guidance if your documentation is quite detailed.

Note: Due to the cadence of the release cycle, feature documentation needs to be complete and submitted as to allow sufficient time for review and to ensure it's included in the release documentation update.

The supplied content can be provided informally, in bullet points, or rough notes in a Google Doc/on the PR itself. Refinements are made collaboratively.

Feature documentation MVP (Product Managers)

A is available to help Product Managers and Techical Writers capture details about new features and functionality that need product documentation.

This is a guideline of what MVP feature documentation can include. Requirements vary based on the scope of the change, so not everything will always be needed:

  • A link to the feature/product's tech spec.

  • Links to any relevant Jira/GitHub issues.

  • A description of the product/feature/update which forms the basis of the documentation.

  • Steps for any processes or procedures (configuration of a feature, troubleshooting, etc).

  • Any FAQs or troubleshooting questions if relevant.

  • Any limitations, issues, or known problems.

  • Configuration settings and examples for the config.json file if relevant.

  • (If possible) Suggestions of where in the docs the content should go.

When the content has been refined and approved in draft format:

  • The Product Manager/Technical Writer creates a branch off the relevant documentation release branch.

  • The documentation is updated with the approved content in that branch.

    • If there are multiple pages to update for a specific feature/change please keep them all in the same branch for ease of management.

  • The PR is submitted and relevant reviewers added, including an editor (not the Technical Writer who wrote the docs), for final review.

    • Include the link to the server/webapp repo issue in your PR for reference purposes.

  • Once all reviews are complete, the PR is marked as Reviews Complete and merged into the documentation release branch by @amyblais.

Once your PR is submitted, there's a review process that includes an editorial review, a PM review, and sometimes a dev review. During the editorial review, editors may make punctuation and/or terminology changes and commit them to save time on the review process. This only applies to punctuation/terminology - content suggestions and questions will follow the usual review and discussion process.

Add reviewers to PRs

Mattermost documentation covers a number of different topics. For documentation, the following reviewers are recommended:

Editor Review

  • Carrie Warner (@cwarnermm)

  • Justine Geffen (@justinegeffen)

Product Manager Review

  • Product: Ian Tao (@tao); Winson Wu (@wuwinson)

  • Integrations: Sandy Atkinson (@asatkinson)

  • Security: Daniel Schalla (@dschalla)

  • Server/calls: Neil Barnett (nab-77)\

  • Self-serve: John Lugtu (@johndavidlugtu)\

  • Growth: Eric Sethna (@esethna)

  • Handbook and Process; Community: Jason Blais (@jasonblais)

Dev Review

If your change requires dev review add the developer/s you've been working with as the reviewer/s. If you're unsure who to add as a dev reviewer you can select one of the team leads below:

  • Product: Scott Bishel (@sbishel)

  • Integrations: Catalin Tomei (@catalintomai)

  • Growth: Maria Nuñez (@marianunez)

  • SRE: Stylianos Rigas (@stylianos)

  • Cloud Platform: Spiros Economakis (@spiros)

  • Mobile: Elias Nahum (@enahum)

  • Web/desktop app: Pantelis Vratsalis (@pantelis)

  • Security: Daniel Schalla (@dschalla)

  • QA: Saturn Abril (@saturninoabril)

Providing editorial feedback

You can read more about the review process .

You can find additional guidance around formatting .

Once the review is complete, we'll move your contribution to the appropriate part of (if it's not there already) and then merge it. We'll share the URL and you can edit it at any time if you need to.

The full list of R&D teams is available .

If you're asked to provide editorial feedback on a PR, and it's your first editorial feedback request, first read up on the review process to get an idea of what's expected in terms of turnaround time, type of feedback, and so on.

Editorial feedback is based on the guidelines laid out in the as well as the .

docs.mattermost.com
per the release process
Mattermost PM feature template
here
here
docs.mattermost.com
here
here
Documentation Style Guide
Voice, Tone, and Writing Style Guide