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:
US 18F: About this guide | 18F Content Guide
Novell: Open Source Documentation Style Quick Start