Technical Writing Team Handbook

1% Draft

Technical Writing Handbook

The Mattermost Technical Writers focus primarily on writing, editing, and maintaining technical documentation (including the User's Guide, Administrator's Guide, and Developer documentation).

Areas of Responsibility

@justine.geffen:

  • Documentation for:

    • DevOps Command Center

    • Integrations (Admin Guide, plugin documentation, and developer journey)

    • Self-serve customer journey

  • Documentation metrics

    • 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.

In addition, the Mattermost Documentation Management and Maintenance guide provides details related to general documentation tasks and processes, applicable across the Mattermost documentation.

Technical Documentation Processes

The processes around documentation, such as SLAs for issues and requesting documentation assistance are detailed below.

Contributing to Documentation

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.

Submitting Feature 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.

Feature Documentation MVP (PMs) - WIP

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.

Submitting Documentation With Your PR

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.

Adding Reviewers to PRs

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

Editor Review

  • Amy Blais (@amyblais)

  • Justine Geffen (@justinegeffen)

Product Manager Review

  • Admin Guide - Enterprise: Dennis Kittrell (@thefactremains)

  • Admin Guide - Security: Katie Wiersgalla (@kwiersgalla)

  • Admin Guide - Cloud: Adam Clarkson (@adamjclarkson)

  • Admin Guide - Licensing: Eric Sadur (\@esadur)

  • End User Guide - Mobile and desktop app: Eric Sethna (@esethna)

  • Apps and Marketplace: Aaron Rothschild (@aaronrothschild)

  • DevOps Command Center: Ian Tao (@itao)

  • 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:

  • 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)

  • Webapp and desktop: Dean Whillier (@deanwhillier)

  • Server/infra: George Goldberg (@grundleborg)

  • Cloud: Joram Wilander (@jwilander)

  • Security: Daniel Schalla (@dschalla)

  • DevOps: Jason Deland (@jaydeland)

  • QA: Linda Mitchell (@lindalumitchell)

  • Handbook and Process: Jason Blais (@jasonblais)

The full list of R&D teams is available here.

Requesting Documentation via Doc Up

Requests for documentation can be made within community.mattermost.com, using the Doc Up plugin embedded in the post menu.

Access the Doc Up plugin by hovering over a message and clicking the "..." 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.

Turnaround Time

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.

Assignees

Documentation does not have to be written by the Technical Product 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 or @amyblais in GitHub.

Community Involvement

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.

i18n Contributions

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:

  1. Do you have an active test instance running with the integrations guide translated so we can validate the rendering and formatting?

  2. 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?

  3. If the intention is to translate the screenshots, is there a proposed process for keeping them up to date?

  4. Have at least one member of UX team and one member of Apps PM team review the user experience in choosing different languages.

  5. 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.

  6. Decide if we want to indicate translations level - e.g. “Alpha” or “Beta” for translations that are in progress.

  7. Test you can successfully rate a translated docs page by selecting a rating emoji. Ping @justine.geffen for validation of this.

General Contribution Workflow

Jira Tickets

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:

  • Label: Documentation

  • 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.

Editing Requests

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.

Providing Editorial Feedback

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.

Editorial feedback is based on the guidelines laid out in the Documentation Style Guide as well as the Voice, Tone, and Writing Style Guide.

Formatting and Style Guide

The Documentation Style Guide and UI text guidelines.

Community Documentation Involvement

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

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/Doc Issues

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.

Engineering/Developer Documentation

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.

Visit the Contribute to Documentation page to get started with submitting documentation with your PR. You can read more about the review process here.