The Mattermost Technical Writers focus primarily on writing, editing, and maintaining technical documentation (including the User's Guide, Administrator's Guide, and Developer documentation).
DevOps Command Center
Integrations (Admin Guide, plugin documentation, and developer journey)
Docs page ratings via Google Analytics
Google Analytics metrics for page visits, read times, and bounce rates
Consultation and guidance for R&D feature team release documentation
Contributing to product documentation
Writing MVP documentation
Admin-facing UI content writing, collaboration, and reviews
Documentation processes for release PRs
Community and doc review process
Process for Doc Up plugin
Docs review and coordination with @amy.blais
Community Help Wanted doc issues
Content and processes
Documentation Handbook and Style Guide maintenance
Documentation processes for Integrations and Workflows teams
The following areas remain a collaborative effort between Product Managers, Engineers, and Technical Writers until additional headcount is reached. Please reach out to the Documentation Working Group for any questions.
GitLab documentation for:
GitLab helm chart docs
Admin-facing UI Content, such as the System Console
Developer-facing UI content, such as the Integrations backstage
In addition, the Mattermost Documentation Management and Maintenance guide provides details related to general documentation tasks and processes, applicable across the Mattermost documentation.
The processes around documentation, such as SLAs for issues and requesting documentation assistance are detailed below.
The basic outline for getting started with contributions is provided in the README of the docs repo. If you have write access to the repo, you can create a branch off master and work on that.
Once complete, submit your Pull Request (PR). Ensure that you assign appropriate approvers and labels. You can read more about the review process here - it applies to various types of contributions including documentation.
Feature documentation is a joint effort between Product Managers 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.
Note: Due to the cadence of the release cycle, feature documentation needs to be complete and submitted as per the release process 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/Jira issue/on the PR itself. Refinements are made collaboratively.
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
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
You can read more about the review process here.
We want to empower everyone to contribute to our documentation, and be comfortable submitting documentation for contributions. As such, we don't expect every contribution to adhere to our style guide when first submitted.
During the review process the editorial team also provides feedback on style elements to bring the submission in line with the Documentation Style Guide.
Here are some guidelines:
When submitting a PR, please include updated documentation if applicable
The documentation update can be in the form of a bullet list or an outline
Label the PR as Docs Needed/Editor Review and tag @justinegeffen or @amyblais
The documentation you've submitted will be reviewed
At times, the editors may make and commit stylistic changes (such as punctuation) but any content changes will be added as a suggestion for the submitter's consideration
Once the PR is approved, it will be merged, and the documentation will be updated
You can read more about the review process here.
Note: This process does not apply to the API Documentation requirements as it is updated automatically and isn't part of the documentation process.
Mattermost documentation covers a number of different topics. For documentation, the following reviewers are recommended:
Amy Blais (@amyblais)
Carrie Warner (@cwarnermm)
Justine Geffen (@justinegeffen)
Product Manager Review
Admin Guide - Enterprise: Adam Clarkson (@adamjclarkson)
Admin Guide - Security: Katie Wiersgalla (@kwiersgalla)
Admin Guide - Cloud: Adam Clarkson (@adamjclarkson)
Admin Guide - Licensing: Jason Blais(\@jasonblais)
End User Guide - Mobile and desktop app: Eric Sethna (@esethna)
Apps and Marketplace: Aaron Rothschild (@aaronrothschild)
Incident Collaboration: Ian Tao (@itao)
Handbook and Process; Community: Jason Blais (@jasonblais)
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:
Core Enterprise Features: Scott Bishel (@sbishel)
Core Features: Scott Bishel (@sbishel) (\interm)
Integrations: Catalin Tomei (@catalintomai)
Workflows (DOCC): Jesse Hallam (@lieut-data)
Cloud Features: Maria Nuñez (@marianunez)
SRE: Joram Wilander (@jwilander) (\interm)
Cloud Platform: Joram Wilander (@jwilander)
Mobile: Elias Nahum (@enahum)
Web App and Desktop App: Dean Whillier (@deanwhillier)
Server/infra: George Goldberg (@grundleborg)
Cloud: Joram Wilander (@jwilander)
Security: Daniel Schalla (@dschalla)
QA: Linda Mitchell (@lindalumitchell)
Handbook and Process: Jason Blais (@jasonblais)
The full list of R&D teams is available here.
Requests for documentation can be made within community.mattermost.com, using the Doc Up plugin embedded in the post menu.
When you select Doc Up and choose Admin as the issue type, an issue is generated in the GitHub docs repo, and added to the issues list. An update is listed in the Documentation channel, with the issue link.
You can also select Developer or Company Handbook to direct the Doc Up request to the appropriate repo.
As the issues are open to the community, the more information provided in the issue the better.
Review the issue in the docs repo, developer documentation repo, or handbook repo and add any links to appropriate documentation and/or Jira tickets. This ensures that the assignee is able to take on and complete the work within the turnaround times.
When the issue has been created, please follow these guidelines to assign labels. This ensures that the issues are prioritized appropriately.
You can expect the following approximate turnaround times:
Urgent issues (bug, customer request/dealbreaker): Acknowledged within 24 hours
General issues: Acknowledged within 48 hours
There are a number of variables at play, such as review process, current workload, and type of work required which makes it difficult to provide a hard and fast time-frame for completion. Large projects might be moved to Jira if required.
Documentation does not have to be written by the Technical Writer/s. You can raise an issue, complete the requirement, and submit a Pull Request. For less urgent work, if no reply has been received within 48 hours, please ping @justinegeffen, @cwarnermm, or @amyblais in GitHub.
We really want the community to own the docs as much as possible. In light of this, please mark your issue as Help Wanted so that community members are able to identify work that they’re able to assist with.
If your documentation request/issue applies to a repository other than mattermost/docs, you can use the Docs Needed and Editor Review labels and/or ping @justinegeffen or @amyblais.
Note: This process is a 1% draft.*
Our User's Guide and Administrator's Guide are available for translation contributions. Join the i18n channel on our Community server and connect with our translation community members. The documentation translation process is still being defined.
Currently, submitting a translation PR follows the same writing and editing process as other PRs. However, there are additional considerations to bear in mind when submitting your PR as these assist with the approval and merge process:
Do you have an active test instance running with the integrations guide translated so we can validate the rendering and formatting?
If the content you're translating includes screenshots should we keep the original English versions of the screenshots, or consider translated versions of them too?
If the intention is to translate the screenshots, is there a proposed process for keeping them up to date?
Have at least one member of UX team and one member of Apps PM team review the user experience in choosing different languages.
To maintain high standards for translated documentation, set up a process to notify translators when something is changed in the English-version of the docs, and expectation on correcting translations for new releases.
Decide if we want to indicate translations level - e.g. “Alpha” or “Beta” for translations that are in progress.
Test you can successfully rate a translated docs page by selecting a rating emoji. Ping @justine.geffen for validation of this.
The Technical Writing Jira board is a snapshot of the current Technical Writing workload.
If you have a feature, UI copy, or general documentation requirement, please create a ticket and include the following fields:
Team: Tech Writing
Assign the ticket to the relevant writer.
If required, select a due date, sprint, and mana.
For best results, please include as much content, context, and detail as possible.
Jira Turnaround Time
If the Jira ticket is for documentation related to a release, the documentation needs to be complete at least 10 days prior to release. Please ensure you allow sufficient time for your request to be completed or it will be moved to the next available slot.
If the Jira ticket is for general documentation, depending on the current workload, you can generally expect it to be completed within five business days.
When submitting a PR for documentation, whether it's a minor update, a new piece of content, or a content proposal, please add the Editor Review label. Once the Technical Writer/Editor has reviewed the PR they'll remove the label. When all the requested reviews are complete, the Reviews Complete label is applied and the changes are merged.
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 here to get an idea of what's expected in terms of turnaround time, type of feedback, and so on.
Every month the Mattermost community plans, builds, tests, documents, releases, and supports new product improvements for Team Edition to benefit the user community. The Mattermost Enterprise Team does the same for Enterprise Edition to benefit the subscriber community.
A critical part of this development is documentation which ranges from feature documentation to FAQs, guides, and tutorials.
Feature documentation is a collaborative effort between the Product Manager and Technical Writer within a specific timeframe aligned with releases. Community members are welcome to assist, if the time expectations are manageable.
Feature request documentation is usually located in the mattermost-server repo and the mattermost-webapp repo and are labelled as
Docs/Needed. As these are tied to a release (and a deadline) it’s best to only take on the work if you’re sure you can complete it on time. It’s understood that community members contribute in their available time, which is why this type of documentation isn’t usually the best option to take on.
Help Wanted tickets are generally not linked to a release and are more flexible in terms of timeline and delivery date. You can find the documentation Help Wanted tickets here. To start working on one, assign it to yourself, add a comment indicating you’ll be working on it, find the relevant document in the source directory, read through the README file if you're not familiar with the process, and get started.
If you have any questions, you can post them in the Documentation channel and we'll be happy to help.
Most, if not all, contributions to the Mattermost project have a documentation impact. As part of the development and submission process, it’s recommended that the relevant documentation be updated (or created) and included in the PR. This provides consistency and accuracy in communicating the changes/new feature and cuts down on having multiple issues and PRs for related documentation.