Technical Writing team handbook
Technical Writing Handbook
Mattermost Technical Writers focus primarily on writing, editing, structuring, and maintaining Mattermost technical and product documentation, end user documentation for Mattermost Channels, Boards, and Playbooks, as well as developer documentation and the company Handbook. Technical Writers also manage in-product microcopy, provide editorial reviews for all documentation across the organization, and work closely with the community to improve documentation.
Areas of responsibility (AORs)
Documentation and technical writing at Mattermost covers (but isn't limited to) the following verticals:
Channels
Mattermost Cloud
Self-managed deployments
Messaging features and functionality
Playbooks
Boards
Calls
Growth
Self-service
Customer Portal
Telemetry
Apps Framework and Marketplace
Other areas of documentation include:
Mattermost Handbook
Integrations (developer documentation, plugin documentation, and developer journey)
Documentation metrics:
Docs page ratings via Google Analytics
Google Analytics metrics for page visits, read times, and bounce rates
Customer feedback analysis
Metrics dashboards using RudderStack
In-product messaging and interface
GitLab documentation for:
GitLab helm chart docs
Developer documentation for:
developers.mattermost.com, including Contribute, Integrate, and Extend sections
General developer experience docs, e.g. code samples, best practices, and tutorials
Community and doc review process
Process for Doc Up plugin
Docs review and release coordination
Community Help Wanted doc issues
Content and processes
PR reviews across the organization
Documentation processes for release PRs
Please reach out to the Documentation Working Group for any questions.
How to contribute to the documentation
Our documentation is open to contributions from anyone. 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 - if you've forked the repo or don't have the correct repo permissions you may not be able to do this, so you can skip this step. Read more about the review process here - it applies to various types of contributions including documentation.
PR tips and best practices
Try to submit files in batches rather than single PRs for each file update. This reduces the PR load and also groups your changes more effectively.
When there are lots of changes requested, especially on a docs PR that doesn't require QA testing, you can use the "Add suggestion to batch" feature in GitHub to commit all of the suggestions at once. You need to be on the Files changed tab to use this feature, though it's also shown on the Conversation tab. By batching your suggestions, you can use one commit message such as "Added batch suggestions from @Carrie Warner". This just makes the commit history of the PR a lot more readable and useful for everyone reviewing it.
Descriptive PR titles and commit messages go a long way, especially when the PR is referenced in the future. The default PR titles that GitHub gives us like "Updated README.md" are not very helpful because there's no way to know the purpose of the PR by reading the title. For example, if the whole file was translated to Japanese because we realize that's our main audience, that information isn't obvious unless you open the PR and read it - or if it's in the PR title.
Style Guide and UI writing guides
Our [Documentation Style Guide] is a guide to writing Mattermost product documentation and includes guidelines around punctuation, casing, and how to format files. We also have a guide for writing UI copy which includes tip, best practices, and examples.
i18n contributions
Note: This process is in flight.*
Our product documentation is 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, and @cwarnermm is the DRI along with members of the Localization team.
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.
Set up a local development environment
Members of the writing team have two ways to contribute to Mattermost product documentation:
Using GitHub web tools. See the GitHub training section below for details.
Working within a local development environment. See the mattermost/docs repository README documentation for details on setting up a local environment.
Clone a documentation fork locally
Mattermost product documentation contributions can be created in one of two ways:
As a branch (applies only Mattermost staff with appropriate GitHub repository permissions).
As a fork (applies to all other documentation contributions).
In a GitHub documentation PR, branched contributions display using the branch name, and forked contributions display as username/reponame:branchname
instead. While branched contributions are automatically pulled down to a local environment when you run the command git pull
or git fetch origin
from the command line, forked contributions must be pulled down manually.
To work with a forked contribution locally:
In the GitHub PR, identify the contributor's username.
In your local file system, create a new directory for the fork.
Navigate to the new directory, then clone the fork by running the command
git clone https://github.com/username/reponame
. Note that you don't need to specify the branch name.Switch to the branch you want to explore by running the command
git checkout branchname
.(macOS users only) Sync your virtual environment for the new directory by running the command
pipenv sync
.
Extend Sphinx functionality
Extending product documentation functionality typically involves extending the Sphinx static generation tool with extensions that introduce new display, page, build, navigation, or output capabilities. For example, all code blocks on all pages of the product documentation feature a copy/paste option to make trying out code samples easy for documentation visitors. The copy/paste option was added by installing a Sphinx extension created by an open source contributor.
To get started with Sphinx extensions, you'll want to set up a local development environment, then identify an open source Sphinx extension you want to test based on an outcome or goal you're looking to achieve that improves the learning experience for Mattermost documentation visitors.
In a local documentation development environment, from the command line terminal, install the Sphinx extension using the installation instructions provided by the extension author.
Regenerate the
pipenv.lock
file by running the following command:pipenv install sphinx-extension==version
whereversion
is replaced with the extension's release version you want to use.Update the
conf.py
file to add the extension in theextension
section.Incorporate the new Sphinx extension on a documentation page using appropriate syntax.
Build the documentation locally to test how the extension works. Be sure to test as many edge cases and real world situations as you can to ensure that the new extended functionality won't break existing pages or content.
Upgrade Sphinx
Mattermost product documentation is generated using Sphinx v4.4. As new Sphinx functionality becomes available, it can be desirable or necessary to upgrade Sphinx to a later release.
To get started with a Sphinx upgrade, you'll want to set up a local development environment, then review the Sphinx release history to identify the upgrade version you want. It's important to understand and test upgrades locally to identify any risks an upgrade may introduce to the Mattermost documentation.
Once you have a Sphinx upgrade version in mind:
In a local documentation development environment, from the command line terminal, install the Sphinx upgrade by running the following command:
pipenv install sphinx==version
. This command updates both thepipfile
with the latest Sphinx version and regenerates thepipfile.lock
.Sync your virtual environment for the new Sphinx version by running the command:
pipenv sync
.Create a documentation PR containing the two file changes to
pipfile
andpipfile.lock
.Once the PR merged into production, writers can update their local development environments to use the Sphinx upgrade by running the following command:
pipenv sync
.
Following a successful Sphinx upgrade, complete the following checklist tasks to ensure that the new version of Sphinx doesn't impact existing functionality, content, or output.
Sitemap generation
Open the latest sitemap via
docs.mattermost.com/sitemap.xml
in a browser tab.Generate the product documentation, then use a text compare tool such as text-compare to review the differences between the newly generated sitemap against what's available in production.
You shouldn't see any glaring differences and the sitemap should NOT have any Mattermost version information in any of the URLs. You may see content move around on the page. Confirm that page URLs in production continue to exist in the latest generated sitemap XML file.
Page redirects
Spot check a handful of redirects specified via the conf.py
file to ensure they continue to redirect visitors correctly.
Parallel processing and pickling
When you build the documentation locally, is the build fast? Do you see a message in the terminal indicating that pickling was successful?
If the build takes more than a few minutes to complete, or you don't see the pickling success message, this could indicate an issue with the Sphinx version, and you may want to reconsider an upgrade to this version.
HTML output
After successfully building the product documentation:
Navigate around the site to ensure that nothing looks or feels broken.
Review pages with tables and tabbed content to ensure the content displays as intended.
Review the landing page as well as subsequent page headers/footers to ensure links take users to expected destinations.
Review the Changelog pages (which are managed in Markdown source files) to ensure that the changelogs are converted to HTML correctly.
Perform a few docs searches to confirm that searches continue to work as expected.
Build warnings and errors
Review and fix issues reported via the /build/warnings.log
file including broken links, pages missing from the LHS, and syntax and formatting problems.
Review documentation repository setup instructions
In GitHub, review the mattermost/docs repository README file and this Handbook process documentation to ensure content accuracy.
GitHub training
GitHub training videos coming soon!
Add PRs to monthly documentation release branches
If you encounter a documentation PR that should be included in a monthly documentation release cycle, instead of tracking the PR individually, the PR can be merged into a documentation release branch.
In the PR, identify the branch name you want to include in a documentation release branch.
Ensure your local development environment is up-to-date and contains the same code as the
master
branch.Navigate into the branch where you want to merge in the PR to ensure all code is available locally.
From a terminal, run the command
git merge branchname
wherebranchname
is the name of the branch you want to commit to a monthly documentation release.If there are no conflicts, you'll see the vi editor. Review the commit message, then type
:x
to save and exit. If there are conflicts, you need to resolve them on the CLI and commit them first before you can move to the next step to push remotely.Push your changes remotely by running the command
git push
.
Last updated