Style Guide Updates #793

esethna · 2017-01-17T17:56:52Z

Updates to doc guidelines based on feedback from PM team in Style guide #642
Some other updates to the RST guide to make it quicker to reference and add a few more tips
Replace the existing "documentation guidelines" doc with the new one.

@JeffSchering please take a look when you have a chance!

JeffSchering

You made some good changes here,

JeffSchering · 2017-01-17T18:45:33Z

source/process/sg_grammar-spelling-mechanics.rst

+Keyboard buttons   Key1+Key2           "Press CTRL+U to upload a file."
+Placeholder field  {placeholder}       "Use the URL in the form of {domain}.mattermost.com/{team}."
+=================  ==================  =============================================================
+


{domain}.mattermost.com/{team}

This should be {hostname}.mattermost.com/{team}... mattermost.com is the domain

JeffSchering · 2017-01-17T18:54:05Z

source/process/sg_grammar-spelling-mechanics.rst

 Avoid
-  Failed sign in? No problem! Simply enter the correct password and we'll let you in right away.
+  The *Status* pane is will be opened by the system.
+


The *Status* pane is will be opened by the system.

This should be The *Status* pane is opened by the system.

JeffSchering · 2017-01-17T19:43:09Z

source/process/documentation-guidelines.md

----
-Type "mattermost-integration-giphy" in the **repo-name** field, then click Search and then the *Connect* button once Heroku finds your repository
-
----


This change moves the style guide.

From: Core Team Handbook > Documentation Style Guide

To: Core Team Handbook > Development Process > Documentation Guidelines

Is that your intent?

I think the style guide should remain at Core Team Handbook > Documentation Style Guide

But if you do want to move the guide, you need to update core.rst also.

Good catch, I've updated the core.rst to maintain the location in the TOC

JeffSchering · 2017-01-17T21:29:15Z

source/process/sg_grammar-spelling-mechanics.rst

-Preferred
-  You can view the status in the *Status* pane.
+Use title case for page titles and section titles.



I find that the page is more visually appealing, and it's easier to scan and pick out structure when title case is reserved for page titles, and section titles use sentence case, especially for short sections. Sections are subordinate to the page and so their titles should not have the same appearance as the page title.

In any case, the conversion of section titles to title case in this PR is inconsistent... some have it, many do not.

I would say that almost all our documentation currently uses title case as the standard. The visual separator between page titles and section titles would be the size of the heading, when PM's discussed we thought that was sufficient. Are you okay with using title case as the standard for now and we can revisit if it comes up again in the future?

ok. Just make it consistent in this doc.

JeffSchering · 2017-01-17T21:36:46Z

source/process/sg_grammar-spelling-mechanics.rst


-Try to keep sentences to 25 words or less in length. Short, single-clause sentences are often easier to understand and easier to translate.
+Try to keep sentences to 25 words or less in length. Short, single-clause sentences are often easier to understand and easier to translate. Tools such as the `Hemingway writing app <http://www.hemingwayapp.com/>`_ can be helpful in checking for readability.



Might be useful to mention a target readability level.

JeffSchering · 2017-01-17T21:38:15Z

source/process/sg_grammar-spelling-mechanics.rst

 Preferred
-  The cows ran from wolves, coyotes, and mosquitoes.
+  If login fails due to an invalid password, turn Caps Lock off and then attempt to re-enter your password. 



If login fails due to an invalid password, turn Caps Lock off and then attempt to re-enter your password.

Probably don't need the word "attempt" here.

JeffSchering · 2017-01-17T21:42:26Z

source/process/sg_grammar-spelling-mechanics.rst


-Use active voice in preference to passive voice. Active voice has the subject of a sentence doing the action. In passive voice, the subject has an action done to it. Use passive voice only when you want to emphasize the action more than the subject.
+In general, Mattermost documentation will use the serial comma unless doing so decreases clarity and understanding of the sentence.



In general, Mattermost documentation will use the serial comma unless doing so decreases clarity and understanding of the sentence.

Maybe: "Use the serial comma unless doing so decreases clarity and understanding of the sentence".

JeffSchering · 2017-01-17T22:02:49Z

source/process/sg_rest_markup.rst

+    :scale: 50 //number is a percentage

 Inserting an inline image is a bit more complicated. It's a two-part construct that consists of a label and the image directive. Surround the label text with vertical bars, the `|` character. For example:



" ... with vertical bars, the `|` character. ..."

Should have two backticks in reST: " ... with vertical bars, the ``|`` character. ..."

JeffSchering · 2017-01-17T22:07:13Z

source/process/sg_rest_markup.rst

-On output to HTML, the link looks like this: https://www.mattermost.org/manifesto/.
-
-You can also create a link that has link text. For example:
+Embed links into text using the following formatting, ```{text} <{url}>`_``, for example:


Embed links into text using the following formatting, ```{text} <{url}>`_``, for example:

I think doing it this way is less clear because there's so many non-alphanumeric characters involved in making a link. It's easy to think that { and } are part of the construct.

I think this okay given that we have the example to help clarify?

How about:

`Link display text <URL-of-website>_`

Also, I think "Embed links" might not be the best way; 'embed' is usually used for embedding images and object into the page. Probably better to say "Create links to external websites ..."

JeffSchering · 2017-01-17T22:09:41Z

source/process/sg_rest_markup.rst

-
-On output to HTML, the link looks like this: https://www.mattermost.org/manifesto/.
-
-You can also create a link that has link text. For example:


By removing this, are you trying to say that "naked" links like this https://www.mattermost.org/manifesto/ are not allowed, and that all links must have a name and be of the form `Mattermost Manifesto <https://www.mattermost.org/manifesto/>`_?

Yes. "Naked" links look messy in my mind, I think we should try to embed them in the text unless there is a reason to show the link.

unless there is a reason to show the link.

Exactly. So we need to cover the case that you would want to show the link.

I've added a sentence to talk about naked URLs but mentioned that hyperlinks in text are preferred

lfbrock · 2017-02-01T19:09:38Z

source/process/sg_rest_markup.rst

 ------------

-For bullet lists and sublists, use only the - character. For example:
+For bullet lists and sublists, use `-` before the list item. For example:


Do we want - or - here?

lfbrock · 2017-02-01T19:10:34Z

source/process/sg_rest_markup.rst

-In reStructuredText markup, the double colon marks the start of a section of literal text that corresponds to the HTML <pre> tag. However, the Sphinx processor applies syntax highlighting for Python to literal blocks, which is not always desired in Mattermost documentation.
-
-To use a literal block as originally intended in the reStructuredText specification, you must cheat a little, and use the Sphinx code-block directive with the language set to `none`. For example:
+To use a literal block with no syntax highlighting, use the Sphinx code-block directive with the language set to `none`. For example:


Formatting on none, does this follow the guidelines / should we update guidelines if it's not covered?

lfbrock · 2017-02-01T19:11:54Z

source/process/sg_rest_markup.rst

+Internal Links to Mattermost Docs
+----------------------------------

 The Sphinx processor extends reStructuredText to implement references to locations within a documentation set. The extensions are called `roles`, and the two roles that are relevant in Mattermost documentation are the ``:doc:`` role and the ``:ref:`` role.


Should we update guideline to include the formatting for roles ? It's not clear if we should be using roles, "roles", or something else

lfbrock · 2017-02-03T17:52:39Z

+1

Eric Sethna added 7 commits January 16, 2017 14:17

Rename mattermost-doc-style.rst to documentation-guidelines.rst

c98e925

Delete documentation-guidelines.md

6a66fb6

add toc section

63cdc68

tweaks from PM discussion

3f11721

Update sg_grammar-spelling-mechanics.rst

9f32c65

Update sg_rest_markup.rst

a68430c

Update sg_document-structure.rst

da76d2b

esethna added 1: PM Review Requires review by a product manager Needs PM Review #2 labels Jan 17, 2017

esethna requested review from jasonblais and lfbrock January 17, 2017 17:56

Eric Sethna added 2 commits January 17, 2017 11:11

Update sg_grammar-spelling-mechanics.rst

9fae050

Update sg_grammar-spelling-mechanics.rst

3305e99

JeffSchering reviewed Jan 17, 2017

View reviewed changes

jasonblais added the Awaiting Submitter Action Blocked on the author label Jan 19, 2017

Eric Sethna added 3 commits January 26, 2017 13:41

Minor tweaks and typos

2e66951

Minor tweaks

4ab6331

Move doc guidelines

47f39e8

esethna removed the Awaiting Submitter Action Blocked on the author label Jan 26, 2017

JeffSchering added the Awaiting Submitter Action Blocked on the author label Jan 27, 2017

JeffSchering mentioned this pull request Jan 31, 2017

Update style guides documentation #772

Closed

Eric Sethna added 3 commits January 30, 2017 23:04

Update sg_document-structure.rst

cef8b2f

Update sg_rest_markup.rst

a44cd5e

Update sg_rest_markup.rst

11dfb2f

esethna removed the Awaiting Submitter Action Blocked on the author label Jan 31, 2017

lfbrock reviewed Feb 1, 2017

View reviewed changes

lfbrock added the Awaiting Submitter Action Blocked on the author label Feb 2, 2017

Update sg_rest_markup.rst

32784b4

esethna removed the Awaiting Submitter Action Blocked on the author label Feb 3, 2017

lfbrock removed the 1: PM Review Requires review by a product manager label Feb 3, 2017

jasonblais approved these changes Feb 3, 2017

View reviewed changes

jasonblais added 3: Reviews Complete All reviewers have approved the pull request and removed Needs PM Review #2 labels Feb 3, 2017

esethna merged commit 68fc61a into master Feb 3, 2017

esethna deleted the style-guide-updates branch February 3, 2017 19:58

lindy65 removed the 3: Reviews Complete All reviewers have approved the pull request label Feb 13, 2017


		Try to keep sentences to 25 words or less in length. Short, single-clause sentences are often easier to understand and easier to translate.
		Try to keep sentences to 25 words or less in length. Short, single-clause sentences are often easier to understand and easier to translate. Tools such as the `Hemingway writing app <http://www.hemingwayapp.com/>`_ can be helpful in checking for readability.


		Use active voice in preference to passive voice. Active voice has the subject of a sentence doing the action. In passive voice, the subject has an action done to it. Use passive voice only when you want to emphasize the action more than the subject.
		In general, Mattermost documentation will use the serial comma unless doing so decreases clarity and understanding of the sentence.

		:scale: 50 //number is a percentage

		Inserting an inline image is a bit more complicated. It's a two-part construct that consists of a label and the image directive. Surround the label text with vertical bars, the `\|` character. For example:


		On output to HTML, the link looks like this: https://www.mattermost.org/manifesto/.

		You can also create a link that has link text. For example:

Style Guide Updates #793

Style Guide Updates #793

Uh oh!

Conversation

esethna commented Jan 17, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JeffSchering left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

esethna Jan 31, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lfbrock commented Feb 3, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

esethna commented Jan 17, 2017 •

edited

Loading

esethna Jan 31, 2017 •

edited

Loading