Mattermost Documentation Style Guide

Troubleshooting
1

I’ll be giving the Mattermost Documentation Style Guide, currently known as Documentation Conventions, a bit of an overhaul over the next couple of weeks. The goal of any style guide is to bring consistency to a set of documents. A style guide specifies which of several options should be chosen by someone who is writing or editing a document. For example, is it “internet” or “Internet”, “email” or “e-mail”, and everybody’s favorite controversy, is a serial comma expected, or not?

One thing the style guide is most definitely not intended to do is slow down or otherwise impede contribution to the Mattermost documentation. Contributions are always welcome and none will be rejected due to non-conforming style. If you don’t have time to consume and comply with the guide, no worries!

Input into the guide is welcome. Please reply to this post with your thoughts and ideas. The related issue is here: [[Help Wanted] Update documentation guidelines] ([Help Wanted] Update documentation guidelines · Issue #634 · mattermost/docs · GitHub) In a few days or early next week, I’ll be creating a pull request with an initial version. The PR will be open to comment.

To get an idea of what style guides look like, here are a few examples:
Docker: https://docs.docker.com/opensource/doc-style/
US 18F: About this guide | 18F Content Guide
Novell: Open Source Documentation Style Quick Start
Gnome: https://developer.gnome.org/gdp-style-guide/2.32/gdp-style-guide.html

Thanks!

1 Like
2

I think one place it start is finding an example of some “quick work” contributed by developers, and think about all the different corner cases to cover.

Here’s an example of some fresh documentation that is technically accurate, and probably waiting for guidelines to be applied.

Stuff to think about:

  • When to use the name of the command vs. the name of tool (e.g. Load Test vs. loadtest)
  • When to use pre-formatted text for commands, e.g. loadtest vs loadtest
  • What’s the principle for organizing headings and subheadings?

The MongoDB Style Guide is a good reference as well. We base a lot of our docs work off MongoDB docs.

3

For anyone interested, the first draft of the style guide is here: https://github.com/mattermost/docs/pull/642.

Work is ongoing, and feedback is welcome.

Thanks!