Polishing style guide #6489

shannonbux · 2018-07-16T22:39:59Z

In preparation for the docs sprint, thought this could use a lot of polish.

Questions I could use extra eyes on @jlengstorf @calcsam @m-allanson :

how to make this shorter! It's crazy long. And it'd be cool if it could be downloaded as a printable pdf or something
Wondering if our examples of good articles are good enough (under What are Guide Articles?)
Wondering if the ## Format of a doc ought to be pulled into a new standalone doc (and possibly have real content with commentary inline or something)
Are the rules about plagiarism reasonable (under ## search for content)?

@jlengstorf

In preparation for the docs sprint, thought this could use a lot of polish. Questions I could use extra eyes on @jlengstorf @calcsam @m-allanson : - how to make this shorter! It's crazy long. And it'd be cool if it could be downloaded as a printable pdf or something - Wondering if our examples of good articles are good enough (under What are Guide Articles?) - Wondering if the ## Format of a doc ought to be pulled into a new standalone doc (and possibly have real content with commentary inline or something) - Are the rules about plagiarism reasonable (under ## search for content)?

gatsbybot · 2018-07-16T22:46:53Z

Deploy preview for using-drupal ready!

Built with commit 50ec6dd

https://deploy-preview-6489--using-drupal.netlify.com

gatsbybot · 2018-07-16T22:47:38Z

Deploy preview for gatsbygram ready!

Built with commit 50ec6dd

https://deploy-preview-6489--gatsbygram.netlify.com

gatsbybot · 2018-07-16T22:49:27Z

Deploy preview for using-drupal ready!

Built with commit 259363f

https://deploy-preview-6489--using-drupal.netlify.com

gatsbybot · 2018-07-16T22:49:46Z

Deploy preview for gatsbygram ready!

Built with commit 259363f

https://deploy-preview-6489--gatsbygram.netlify.com

calcsam · 2018-07-16T23:53:34Z

docs/docs/gatsby-style-guide.md

+
+In tutorials that are meant for beginners, use as few hyperlinks as possible to minimize distractions. In docs, it's ok to include as many hyperlinks as necessary to provide relevant and interesting information and resources.
+
+## Begin sentences clearly


Perhaps "indicate optionality" as this is what we're doing?

I'll be honest: I have no idea what "indicate optionality" means.

Can we rephrase that to be friendlier to English as a second language/folks like me who don't read good? 😅

"Clarify when a section is not required"

shannonbux · 2018-07-17T17:39:16Z

Will compare this to a list apart style guide per @jlengstorf 's recommendation

KyleAMathews · 2018-07-17T17:52:15Z

Deploy preview for using-postcss-sass failed.

Built with commit 259363f

https://app.netlify.com/sites/using-postcss-sass/deploys/5b4e2b83c6aed645fe8fd9fb

m-allanson · 2018-07-18T11:34:13Z

Huh I thought I commented on this yesterday but maybe I didn't hit submit.

Here's another technical writing style guide that could be a useful reference: https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines

m-allanson

Looks great!

I left some comments - sorry for the noisy review, a lot of the comments are minor tweaks that I'd usually just do myself, but it's quite a long document so I just added everything as a comment.

m-allanson · 2018-07-18T11:48:07Z

docs/docs/gatsby-style-guide.md

 - [What are Guide articles?](#what-are-guide-articles)
 - [What can I write an article about?](#what-can-i-write-an-article-about)
- [How to contribute](#how-to-contribute)
+- [How to contribute](#how-to-submit-a-pr)


The title and URL don't match here. Maybe they could be switched to [How to submit your article](#how-to-submit-your-article) or similar?

docs/docs/gatsby-style-guide.md

+Before you begin writing, make sure to read the rest of this style guide.

-# How to contribute
+# How to submit a PR


docs/docs/gatsby-style-guide.md

-    find the article stub you'd like to write or edit. All stubs will be in an
-    index.md file.
+    find the article stub you'd like to write or edit. All stubs will end with the .md file ending since they are written in Markdown.
 3.  Click the "Edit this file" pencil icon and make your changes to the file in


m-allanson · 2018-07-18T11:52:40Z

docs/docs/gatsby-style-guide.md

+    find the article stub you'd like to write or edit. All stubs will end with the .md file ending since they are written in Markdown.
 3.  Click the "Edit this file" pencil icon and make your changes to the file in
    GitHub-flavored Markdown.
 4.  Scroll to the bottom of the screen and add a commit message explaining your


Missing opening " around pull request

Do you mean this? "Create a new branch for this commit and start a pull request"

m-allanson · 2018-07-18T11:56:44Z

docs/docs/gatsby-style-guide.md

+# How to submit a PR

 You can create a PR with your draft article (or edits on an existing article) in
 two ways:


These two sections could have headings? Something like Write your article on GitHub and Write your article locally

docs/docs/gatsby-style-guide.md


-Each article should explain exactly one concept, and that concept should be
-apparent from the article's title.
+The introduction paragraph should be a 1-2 sentence explanation of the main


docs/docs/gatsby-style-guide.md

-them to a GitHub repository of your own, then push them to GitHub. Then you can
-right click the image and copy its image source.
+Format language keywords as code - this is done with the backtick key (located
+to the left of the "1" key on a US keyboard) in GitHub-flavored markdown. For


docs/docs/gatsby-style-guide.md

+them to a GitHub repository of your own, then push them to GitHub. Then you can
+right click the image and copy its image source.
+
+Then you'd just need to reference them in your markdown file with this syntax:


docs/docs/gatsby-style-guide.md

+Then you'd just need to reference them in your markdown file with this syntax:
+`[your alt text](your url)`
+
+Then the images should show up when you click the "preview table" tab.


docs/docs/gatsby-style-guide.md

+
 Also, there's a community of support from a whole team of contributors, whom you
 can bounce ideas off of and ask for input on your writing. Stay active in the
 contributors chat room and ask lots of questions.


m-allanson · 2018-07-18T12:19:04Z

@shannonbux in answer to your questions up there:

how to make this shorter! It's crazy long.

Both the List Apart and Digital Ocean styleguides are pretty long too. I don't think we should worry about shortening as long as the structure is good.

Wondering if our examples of good articles are good enough (under What are Guide Articles?)

Hmm those links didn't work for me - they all go to 'Page not found' page

Wondering if the ## Format of a doc ought to be pulled into a new standalone doc (and possibly have real content with commentary inline or something)

I don't understand this question... sorry!

Are the rules about plagiarism reasonable (under ## search for content)?

This section could be more explicit I guess? Something about how it's not OK to copy and paste large chunks of existing content unless you've checked with the author?

Need help formatting code examples within code examples ``` markdown stuff ```shell code ``` <--how do I make sure this doesn't close out the first three backticks? more markdown stuff ```

KyleAMathews · 2018-08-21T00:09:15Z

Deploy preview for using-contentful failed.

Built with commit a0032b8

https://app.netlify.com/sites/using-contentful/deploys/5b80530982d3f15bfffd1a2e

KyleAMathews · 2018-08-21T18:55:15Z

Deploy preview for image-processing failed.

Built with commit e2fac23

https://app.netlify.com/sites/image-processing/deploys/5b7c5ebcfdd72a0f17a0332f

shannonbux · 2018-08-22T19:29:11Z

Would partially finish #4284, #6779, and #6778

shannonbux · 2018-09-04T22:00:10Z

Closes #823 and #4284

shannonbux added 2 commits July 16, 2018 16:38

couple edits

81febf1

calcsam reviewed Jul 16, 2018

View reviewed changes

This comment has been minimized.

Sign in to view

shannonbux requested a review from KyleAMathews July 17, 2018 17:38

updated headers

259363f

m-allanson reviewed Jul 18, 2018

View reviewed changes

Filled out all templates

3d06fb8

Need help formatting code examples within code examples ``` markdown stuff ```shell code ``` <--how do I make sure this doesn't close out the first three backticks? more markdown stuff ```

shannonbux added 3 commits August 21, 2018 10:36

ToC

eeca829

Added section on titles & headers

e0c3e8d

example of commas gone awry

e2fac23

shannonbux added 5 commits August 22, 2018 12:33

updated plugin template

dcb24f1

consistent headers

9442020

formatting fixes

a0032b8

wording edits

c56e50c

formatting

d28385a

shannonbux merged commit 5d5b3c2 into master Aug 31, 2018

shannonbux deleted the style-guide-revamp branch August 31, 2018 17:35

shannonbux mentioned this pull request Sep 4, 2018

[docs] Add template for plugin READMEs #4284

Closed

6 tasks

This was referenced Sep 4, 2018

Tutorial template + gold standard example #6778

Closed

guide template + gold standard example #6779

Closed


		In tutorials that are meant for beginners, use as few hyperlinks as possible to minimize distractions. In docs, it's ok to include as many hyperlinks as necessary to provide relevant and interesting information and resources.

		## Begin sentences clearly

Polishing style guide #6489

Polishing style guide #6489

Uh oh!

Conversation

shannonbux commented Jul 16, 2018

Uh oh!

gatsbybot commented Jul 16, 2018

Uh oh!

gatsbybot commented Jul 16, 2018

Uh oh!

gatsbybot commented Jul 16, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gatsbybot commented Jul 16, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

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!

This comment has been minimized.

This comment has been minimized.

shannonbux commented Jul 17, 2018

Uh oh!

KyleAMathews commented Jul 17, 2018

Uh oh!

m-allanson commented Jul 18, 2018

Uh oh!

m-allanson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

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!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

This comment was marked as resolved.

Uh oh!

m-allanson commented Jul 18, 2018

Uh oh!

KyleAMathews commented Aug 21, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews commented Aug 21, 2018

Uh oh!

shannonbux commented Aug 22, 2018

Uh oh!

shannonbux commented Sep 4, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

gatsbybot commented Jul 16, 2018 •

edited

Loading

gatsbybot commented Jul 16, 2018 •

edited

Loading

KyleAMathews commented Aug 21, 2018 •

edited

Loading