Style guide

[JeffSchering]

Here's the first draft of the proposed style guide. I've broken it up into 4 separate pages. Input welcome! I need to know if I'm on the right track with this.

[it33]

Overall, really nice, some nits in comments. High-level

1. Wondering if this should go into one file so it's easier to have in one place--or not. Interested in your thoughts.
2. Can we remove the out-of-date docs guidelines in this PR while we're at it?

[it33]

Open to discussion.

I'm not sure about breaking into different pages, as it could clutter the navigation. We have typically used sub-sections, which also help when people are searching a page for a term.

[JeffSchering]

There are two approaches to this. One is to have one large monolithic file. The other is to have a docset made up of standalone files that are used where needed via :toctree:. I suppose there are pros and cons to each approach, but I would advocate for more granular, standalone, topic-based files for all Mattermost docs, not just the style guide, for the following reasons:

1. As a general rule, the content is easier to manage when it's broken up into standalone files with one topic per file. For example, if the MySQL config is one standalone file, it can be pulled into any number of Administration doc sets using :toctree: in Sphinx. If something changes and the MySQL instructions need updating, then the change is made in one place and that change automatically propagates to every doc set. If instead the MySQL content is copy/pasted into a dozen long pages, then you need to make sure that you catch every occurrence.
2. Content is easier to find for end users. For example, search the docs for the term database installation (https://docs.mattermost.com/search.html?q=database+installation&check_keywords=yes&area=default) and try to figure out which one of the results has your answer. If instead there was a topic called "Installing PostgreSQL database" it would most likely show up in the search results. Furthermore, when you clicked that result, the page would open and the installation instructions would be right there. As it is, none of the search results look promising, so you end up scanning the toc and clicking around until you find something.

Having said that, it looks like a lot of open source products are going for the monolithic style these days. I suppose you can make use of the :include: directive, which would allow standalone files in the repo and a monolithic file appearing in the published docs. This would leave the options open.

[it33]

Thanks @JeffSchering, propose we try the open source style of monolithic with includes?

Agree on your points of being easier to search and find things, it's just the rest of our docs are monolithic, and if we're going to change it's going to be a larger project.

Maybe add a section in Doc Guidelines about how to organize within a monolith (e.g. maybe with a mini-TOC?) and how to use includes?

[it33]

@JeffSchering not sure your thoughts on trying the monolith vs. separate pages? This PR seems to have a number of short and long pages broken up, did you want them still separate?

[JeffSchering]

I kept the pages separate, but when built they're all included into a monolith, which is what readers will see. See sg_mattermost-doc-style.rst for the ..include:: statements.

Here's an idea of what it would look like when ouput to HTML:

The Document sections stuff is in sg_document-structure.rst and Grammar, spelling, mechanics is in sg_grammar-spelling-mechanics.rst.

[it33]

Perfect, thanks @JeffSchering!

[jasonblais]

We actually use subsections quite a lot and can find them useful.

One sample page is Account Settings where we use subheadings to refer to particular account settings.

Let me know if you'd have any thoughts on that @JeffSchering? Could there be use cases when subsections might work better?

[it33]

Hmm... I wasn't clear the first time I read this what a "decimal number" was, and what was the alternative ("written number"?).

I had the read the examples multiple times and go back to the original description before I figured it out.

Maybe tweak a bit?

I think I learned the term "decimal numbers" when I was in grade school, but haven't thought of them since then...

[JeffSchering]

How about: "Spell out numbers when they are the first word in a sentence, otherwise use numeric digits."

[it33]

Perfect, thanks!

[it33]

1. Should we add an introduction sentence to this section?
2. Should we add formatting to Highlights section to better communicate how each highlight appears?

[JeffSchering]

Yes... more work needed here.

[it33]

Thanks Jeff,

[it33]

Er... kind of confused by this section...

[JeffSchering]

Those are just comments to myself. They should be removed.

[it33]

Thanks Jeff,

[it33]

This section was confusing to me, could we get it to a state where we don't need to go to an external link?

[JeffSchering]

Ok.

[it33]

Thanks Jeff

[it33]

This section was also hard to follow for me. Perhaps add an intro sentence and some examples so it's more clear to someone who's learning, or coming over form markdown?

[JeffSchering]

Makes sense.

[it33]

Thanks Jeff

[it33]

It's a little difficult for me to follow "Menu selections", as I think this referring to documentation about selecting menus, but it's appearing in the RST tutorial section.

My expectation is that the RST tutorial would explain how to make things bold, italic, monospace, etc. and the guideline on how menu items appear would be in a different section?

[JeffSchering]

Yes, that makes sense. The reason I have it here is because if you use the :menuselection: directive, you end up with normal text and a tiny grey right arrow between items instead of bold text with the > character between items. I don't think it's a problem to have the menu selection criteria in a couple of places, so I'll add it into the grammar-spelling-mechanics section.

It's probably worth it to review all the semantic markup elements offered by Sphinx and come up with either a blanket statement about using them or not using them, or specify those which we think should be used.

[it33]

Thanks Jeff, I think for this phase of the project we can maybe stay with basic RST (just what you see when you read our docs) and we can add the more fancy stuff later?

Generally knowledge of RST is low, so what you have to start is excellent. We kind of need the 10% of RST that covers 90% of use.

[it33]

Overall looks good, just a couple of questions in my comments.

@lfbrock could someone from PM be assigned to review and finalize this?

[it33]

Sorry if I missed this, just wondering if we should add a note on file naming convention?

It seems this PR has sg_ as a prefix, which is different from how other pages are organized. If we use a prefix either we're going to be inconsistent across our pages or we'll have to redirect or break links to refactor everything to use prefixes (which is not bad, so long as we know how to do that properly--what we don't want is orphaned pages).

Our file naming isn't consistent yet, we should figure out if file naming is in scope for the style guide

[JeffSchering]

I prefixed the files with sg_ simply to keep them sorted together in a directory listing. I don't think a formal, prescribed, file naming convention is required, although file naming is something to think about. The file name becomes part of the URL for the doc, so it should at least give a hint as to the contents of the doc, and for the most part that's already the case in the Mattermost docs. Let's leave file naming out of the style guide for now, and if it becomes apparent that a formal convention is needed, we can add it in. Even then, I don't think a whole-scale renaming would be called for. We don't know how many web pages outside of the docs point to the existing URLs, and renaming everything would break all that.

[it33]

Thanks @JeffSchering makes sense, we'll leave file naming out of the guide for now, and we can think about it later--along with a strategy for redirecting out-of-date pages.

[jasonblais]

We discussed among PMs and propose we remove the sg_ prefix from the style guide doc file names for now.

The sg_ prefix will appear in the URL when viewing the page on docs.mattermost.com, and could be confusing if a user doesn't associate sg_ with style guide.

We can consider file naming convention later.

[it33]

@JeffSchering not sure your thoughts on trying the monolith vs. separate pages? This PR seems to have a number of short and long pages broken up, did you want them still separate?

[it33]

Thanks @JeffSchering for addressing feedback. The reviews here have taken a bit longer than they should.

When we started I think we didn't yet have a process for @lindy65 to help prompt doc PRs that had been languishing and hopefully there's process for that now.

A few thoughts to think about for PM team outside of this PR:

1. What's the expectation for responses on doc PR reviews?
2. How do we prompt folks to review? (in my mind, doc PR reviews are higher priority than most community forum requests, but we don't seem to treat them that way).
3. Propose having a ticket to document the PR review process for Docs--what's the expectation? How do we get reminded? When do we switch from WIP to a PR ready for merging? When is a doc PR okay going in without a dev review and when is one required?

[it33]

Doc PRs are taking forever, I'm just going to merge this and we can correct anything missed.

[it33]

@JeffSchering sorry, I was going to merge this but it looks like there's some conflict, could you tweak and then we'll merge?

[esethna]

Hey @JeffSchering, sorry for the delayed review on this, PM team is planning to do a group review tomorrow afternoon.

[JeffSchering]

@it33 It should be ok to merge now.

[jasonblais]

Overall great work!

Some feedback attached.

One suggestion is replacing the old documentation-guidelines.md with a new one that combines the document-structure and grammar-spelling-mechanics.rst docs in a single space.

We were thinking we could use it as a single checklist when working on a new doc.

Also, the old documentation-guidelines.md might be obsolete now that we have these new style guides.

[jasonblais]

should this be title cased per "Document Title" guidelines above?

[jasonblais]

We actually use subsections quite a lot and can find them useful.

One sample page is Account Settings where we use subheadings to refer to particular account settings.

Let me know if you'd have any thoughts on that @JeffSchering? Could there be use cases when subsections might work better?

[jasonblais]

General question: Following the guideline of using short sentences, should we avoid the use of semicolons in docs? Does that make sentences structurally more complicated?

[jasonblais]

Serial comma is okay, but I'm not sure about the reasoning.

It sounds that "serial comma is preferred for greater clarity -- but there are edge cases, and therefore we use the serial comma". I assume the serial comma use is preferred due to clarity, so maybe just re-write this paragraph to make it clearer?

[jasonblais]

Wondering if heading and section titles should also be title case?

Or do we have a principle/guideline on why we would use sentence case instead?

[jasonblais]

Few tweaks:

1. Please also help add a guideline for

• keyboard buttons: all capitals with no spaces and no monospace highlighting. Example: CTRL+U
• placeholder fields: inside square brackets, no other highlighting. Example: [team name]
• key strokes in monospace: Example: 10

2. Capitalize the fields under "Text" column (maybe add this part of guidelines for tables)

3. Maybe group commands text formatting with the other monospace options. Perhaps below code samples.

4. Propose replacing "menu selection" and "UI selection" with "Clickable Control", which covers both

[jasonblais]

Should we add any guidelines for tables? For instance center-aligning the title row in tables?

[jasonblais]

maybe group "Verb tense" with tone and voice earlier in the document?

[jasonblais]

could referencing the Hemingway writing app be useful?

It's a common tool to simplify your paragraphs and sentences, which could be helpful for anyone working on docs.

Not sure if you've used the app yourself or if you've used something else before @JeffSchering

[jasonblais]

We discussed among PMs and propose we remove the sg_ prefix from the style guide doc file names for now.

The sg_ prefix will appear in the URL when viewing the page on docs.mattermost.com, and could be confusing if a user doesn't associate sg_ with style guide.

We can consider file naming convention later.

[esethna]

@JeffSchering Thanks for this, it's going to be a super useful guide! PM's met to discuss this PR, see the compiled feedback above. Please feel free to ping me if you have any questions!

[it33]

@esethna @jasonblais could I ask your help to create a new PR for the proposed changes and manage that among the PM team?

• I agree it's not perfect and it does need updates
• At the same time I think it's not okay to be 20 days late on a PR review request and then come in last minute and ask for a ton of changes.

PMs are accountable for the output of the community process, if we're way past any reasonable window for answering a review request, then we should do the updates ourselves--especially when we're still missing any documentation on what community members should expecting for the contribution process.

@JeffSchering's been working on this for a month, we agreed to merge it,

Regarding sg_ this was discussed and I believe Jeff is correct that there is no standard for filing naming right now, therefore there is no reason we shouldn't accept a filename with sg_ .

Moreover, Jeff is using sg_ as the prefix for a series of files combined into one monolithic file with includes, and I personally think that's not a bad system (though we should think about how filenaming plays when a file is included in multiple monolith pages...)

@JeffSchering huge thanks for starting something the entire community can use!