Mattermost Handbook
The Mattermost Handbook is a continual work-in-progress for Mattermost staff (people who are paid to work on our open source software), contributor community, and end user community. We use it to document the processes that underpin our company behind our software. Its purpose is to iteratively increase clarity for Mattermost staff and community co-building the future of our company and our offerings, and provide a single-source of truth.
Early in our history, when we were a much smaller company, our staff handbook was included in our product documentation. Now the Handbook lives in the the dedicated repository at https://github.com/mattermost/mattermost-handbook which is edited using GitBook as a frontend.
Want to contribute to the Handbook? Start here: How to update the Handbook.
All documentation is available under the terms of a Creative Commons License.
Some norms you'll see here in the Handbook:
Growing companies are a work-in-progress
It's Day 1 at Mattermost. We're a growing company and growing open source project out to support the massive transformation underway as open source software unlocks the massive potential of people and teams around the world. As an open source company we like to share early. Sharing ideas early gets us feedback sooner, so we can iterate faster, so we can better results.
On some pages, you'll see reference to 1% and 50% drafts. This is used to express how complete our thinking is around the published content, and indicate whether fundamental changes may be made.
When a section of the handbook is at less than the 50% draft stage you should see it labeled in the page description with the % draft status. When a section doesn't have a % draft status, assume it's over the 50% draft stage.
We believe this system has two key benefits:
- Be more open to feedback and iteration: Having something published publicly can make it seem overly "final". By having pages in our handbook at 1% and 50% we make it easier to go through feedback and iteration cycles.
- Engage more non-technical people in the discussion: In the past, we've done reviews largely in GitHub pull requests, which is friendly and familiar for technical team members, but more difficult for others. Sharing 1% and 50% drafts in the public for feedback makes our process more inclusive.
There are trade-offs as well: There may be confusion among people who haven't been onboarded into the 1%, 50% draft concept. People who aren't comfortable with the level of early sharing may feel upset. For these reasons, this page itself is only a 10% draft, so opinions can be expressed and discussed.
Sharing feedback and updating the handbook
Feedback on this handbook is immensely appreciated. There are two ways you can share your feedback:
- You can create an issue in the Handbook repository. Select New issue, and provide as much detail as possible in the issue. Screenshots and links are also welcome. Choose Submit new issue. The Handbook channel receives a notification and this begins the cycle of feedback and iteration. While not all feedback will result in an update to the handbook, we definitely want to hear everyone's opinion.
- You can edit the page directly, and submit your feedback/suggested changes as a Pull Request (PR). PRs go through the same cycle of feedback and iteration. The only difference is that an issue is not an immediate change and may take longer to action. A PR already contains the changes, and has a quicker turnaround time. Learn how to update this handbook through GitHub for detailed steps.
Key links and materials
Below is a work-in-progress list of key documents and channels at Mattermost. The symbol * indicates material internal to Mattermost staff.