Update style guides documentation

[jasonblais]

1. Add user account and parameter formatting to documentation style guides

From discussion with @JeffSchering #742 (comment)

[JeffSchering]

Style Guide updates

This is a raw, unedited, rough, unofficial list of updates proposed for the style guide. Comments and suggestions welcome!

Text highlighting

Additions to this table: https://docs.mattermost.com/process/mattermost-doc-style.html#text-highlighting

• italicize names of user accounts Eg. Log in to the postgres account.
• italicize placeholder names
• italicize param names in config files when referring to them in the text (not in the file example itself)
• monospace param values in config files when referring to them in the text (not in the file example itself)

Placeholders for user-specific names

• add use of {} around place holders. For eg, "--nginx -d {domain-name} && sudo service nginx reload``

word list

• login vs log in vs log-in
• log in to not log into
• setup vs set up
• sign in vs sign-in
• single sign-on
• can or might instead of may
• downtime not down time

Note about when to apply styleguide:

• when creating a new doc
• when converting a doc from .md to .rst
• when revising a doc, apply styleguide to the part that you changed, unless it would be jarringly inconsistent with the rest of the doc. In that case, if you have time to update the rest of the doc, then do so, otherwise use a style that best fits with the existing doc and create an issue in GitHub to fix the style (perhaps a Help Wanted?)

If updating the style will impact a release or if the scope is significantly greater than originally planned for, then do what you can and what makes sense, and then create an issue in GitHub. For example, "File XXX converted to .rst, but does not meet requirements of the Style Guide."

Titles in top-level parent docs

The title in a top-level parent doc should have both title underline and title overline. The reason for this is so that the Sphinx processor creates the correct hierarchical structure in the ToC.

Parent docs have one or more include statements. Top-level parent docs, in addition to the include statements, are at the root of the hierarchy for that particular topic. For example, source\install\install-ubuntu-1404.rst is a top-level parent doc.

Presenting lists of items and their descriptions

Prefer this markup which results in HTML definition list:

Total Users
  The total number of active accounts created on your system. Excludes inactive accounts.
Total Teams
  The total number of teams created on your system.

Avoid

 **Total Users:** The total number of active accounts created on your system. Excludes inactive accounts.
 **Total Teams:**  The total number of teams created on your system.

Other

• Review comments still outstanding in Style guide #642

• Update underline specs. See https://pre-release.mattermost.com/core/pl/oo5k3en8wtf87jgd5taux67a4w

• How to handle menu selections. For example:

    System statistics are viewable under **System Console > Reporting > Site Statistics**.
  

  instead of

    System statistics are viewable under **System Console** > **Reporting** > **Site Statistics**.
  

• prefer constructs such as you can view over you will be able to view Reason: fewer words, simpler tense

See #825 (comment) for:

@JeffSchering can we add something to style guide that Enterprise Edition features should have a note like this in documentation? We should eventually phase out the (E10), (E20) next to the title, as it doesn't work "(E10)" should technically be "(E10, E20)" and that breaks if we one day add a new SKU.

See #825 (comment) for:

@JeffSchering can we add something to style guide where a) we have "scannable" as a high level objective we're going for, and b) as a guideline, we don't have more than 2-3 sentences without a heading? IT admins today are talking to each other over SnapChat, attention spans aren't as long as they used to be.

See #825 (comment) for:

@JeffSchering also, propose we add to Style Guide:

1. an objective of accurately framing documentation in the context of what is to be achieved,
2. examples of terminology in the context of achievement

Examples of terminology in the context of achievement:

• Use "with continuous operation" to be clear on the desired state and avoid "without service interruption" as a double negative definition.
• Use "with scheduled maintenance downtime" instead of "with service interruption", to make it clear the system should run under IT best practices.

We should also be clear terminology in the context of achievement should always be accurate and should avoid unintentionally overselling a feature,

Please see if we can use the example above on what HA offers as hyperbolic illustration of a correction?

Add rules for Title Case... which words are capitalized, and which ones are not ('and', 'or', etc)

[JeffSchering]

Waiting for PR #793 to get merged, then I'll start working on this.

[JeffSchering]

Closing. Implemented in PR #865