How We Work as a Technical Writing Team at Mattermost

In a recent blog post, I introduced the tech stack our Mattermost Technical Writing team uses every day to build, contribute to, improve, and maintain the Mattermost product documentation at docs.mattermost.com.

Building on this knowledge, I’d like to share more about how we work as a writing team, the branching strategies we’ve learned to adopt, and the review workflows every documentation contribution goes through before being merged into the codebase.

Multiple Paths are Available

One of the things I love most about developing product documentation at Mattermost is how flexible we are about how we work and the tools we use to reach a specific outcome. When I was new to the team, I used GitHub web tools to create and review content PRs. GitHub’s lightweight web tools helped me become familiar with the docs repository and enabled me to focus on content development over the development process. 

Using GitHub web tools, it was incredibly easy to get started. Simply navigate to a product documentation page, select the Edit on GitHub option to go directly to the source page, then make some changes. GitHub’s web tools handle most of the process work, and the author simply provides context for reviewers. The web tools are perfect for small, quick content changes, and for writers new to parallel streams of development.

What the web tools lack is the ability to quickly iterate on bigger scopes of work. As I dove deeper into architectural changes and content reorganization, I found myself spending more time waiting for builds to complete and less time learning through iteration. The faster I wanted to iterate, the more motivated I was to learn to work locally.

It took learning to navigate my local file system, clone repositories, fetch code updates, switch between branches, push changes remotely, and build the product documentation locally — all from a command line interface — for me to truly appreciate the power of working like most developers at Mattermost do. Working locally empowers me to prove out new ideas and execute large-scale changes quickly and confidently.

Branches Enable Parallel Streams of Work

We manage our product documentation source using Git, which is a distributed version control system. Source control systems like Git maintain a linear and chronological list of all changes made to a codebase.

To enable multiple people to contribute to the product documentation at the same time, each contributor works in what’s called a branch. The main stream of development is done on a branch we call master. The master branch is our single source of truth and the code all documentation changes are based on.

Some branches are short-lived and contain a quick correction in a single file while other branches can be long-lived and contain many updates and changes affecting many files. Changes in branches are kept separate from all parallel streams of development work until that work is merged back into master.

Branches Start as a Snapshot of Master

A branch contains the code from the master branch at a specific moment in time. Master continuously changes as new changes are merged in. A branch created off master on a Monday morning will contain different code than a branch created on Monday afternoon if any changes are merged into master in between.

This year, we’ve faced a number of situations that have helped us become more strategic as a team about how we manage our product documentation branches.

We Rebase Long-lived Branches Regularly

We use long-lived branches for monthly release documentation updates. These branches contain only release-specific content updates for a given monthly product release, and they typically include many file changes.

When it’s time to merge a release branch back into the codebase, Git compares the branch code to the code in master. Any conflicts identified between the two sources must be addressed as part of the merge. The longer-lived a branch is, the more likely that branch is out of sync with master — and the more likely there are merge conflicts to manage. 

On release day, the more merge conflicts a team needs to address, the more risk of release delays. To avoid release delays, our Technical Writing team ensures that long-lived release branches are rebased at regular intervals prior to release day. Rebasing ensures that the latest code in master is included in the long-lived branch and that the final merge contains no conflicts.

During the v6.0 development cycle, in addition to working within a release branch for content updates, our Technical Writing team was working through significant structural and content reorganization updates in a separate long-lived branch. At release time, it wasn’t immediately clear to us which long-lived branch to merge in first or why a specific order might matter.

I personally merged the architectural branch first without rebasing, ahead of the release branch merge. It didn’t take long for me to realize I’d made the wrong choice. I faced a long afternoon of merge conflicts to resolve within the release branch. But why? 

• The release branch was created before the structural branch was created. Because the release branch was older, the chances were higher of it containing more conflicts because its version of master was older.
• Merging the structural branch before the content branch introduced a second set of conflicts to the release branch. The release branch needed to be merged on top of master as well as the newly merged structural updates. 

Confused? So were we until we mapped everything out visually!

Going forward, we’ve learned to always merge release branches with content updates before merging any structural updates, and rebase all long-lived branches at regular intervals to ensure that merges back into master are effortless.

Pull Requests Drive Collaborative Reviews

Regardless of the size of the branch or the scope of a documentation change, all branches are bundled into pull requests (PRs) which are used to:

• Notify others that documentation changes are ready for review.
• Manage all discussion and feedback about a set of changes in a single place.

Every documentation change is captured as a PR, and each PR goes through a comprehensive, cross-team review process prior to being merged. Working together in PRs enables documentation contributors and subject matter experts to combine their collective wisdom, experience, and knowledge through feedback, guidance, blindspot checking, knowledge transfer, and context.

In addition to technical accuracy, completeness, and clarity reviews performed by team members in Product Management, Engineering, and Support, the Technical Writing team also provides editorial reviews to ensure adherence to our Documentation Style Guide. Once feedback is gathered and applied, the PR is approved, and the changes are merged back into master and pushed live to production.

The outcome of reviewing so collaboratively using a cross-team approach is technically accurate, peer-reviewed, quality product documentation content that benefits everyone. 

Want to Get Involved?

Have our learning lessons piqued your interest? Looking to get involved with Mattermost product documentation or Mattermost developer documentation? Getting started is easy!

Stop by our DWG: Documentation Working Group Community channel to say hello, then head over to GitHub to browse our open help wanted tickets for Mattermost product documentation and developer documentation sites. 

More hands make lighter work, and we welcome all community contributions! We hope to see you soon.