Skip to content

Commit

Permalink
add notes to Style Guide about "you" as a subject (#18471)
Browse files Browse the repository at this point in the history
  • Loading branch information
Marcy Sutton committed Oct 10, 2019
1 parent 7081933 commit 9323181
Showing 1 changed file with 4 additions and 2 deletions.
6 changes: 4 additions & 2 deletions docs/contributing/gatsby-style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -82,9 +82,11 @@ Also, there's a community of contributors to support you. Bounce ideas off of th

### Use "you" as the pronoun

Your articles should use the second person ("you") to help to give it a conversational tone. This way, the text and instructions seem to speak directly to the person reading it. Try to avoid using the first person ("I", "we", "let's", and "us").
In English, your articles should use the second person ("you") to provide a conversational tone. This way, the text and instructions seem to speak directly to the person reading it. Try to avoid using the first person ("I", "we", "let's", and "us"). For other languages, refer to each translation's guidelines (if applicable) for consistent phrasing.

Using "you" is also more accurate than saying "we," because typically only one person is reading the tutorial or guide at a time and the person who wrote the tutorial is not actually going through it with them, so "we" would be inaccurate. You might notice that some technical documentation uses third person pronouns and nouns like "they" and "the user," which add more distance and feel colder than the conversational and warm "you" and "your."
Using "you" in English is also more accurate than saying "we," because typically only one person is reading the tutorial or guide at a time and the person who wrote the tutorial is not actually going through it with them, so "we" would be inaccurate. You might notice that some technical documentation uses third person pronouns and nouns like "they" and "the user," which add more distance and feel colder than the conversational and warm "you" and "your."

When updating a doc to adhere to this part of the Gatsby Style Guide, one exception in English is when "we" refers to Gatsby's core processes. The subject is the code in this case, rather than a teacher/reader connotation, and should be rewritten or restructured to not confuse the reader about what they are responsible for doing when something is happening automatically behind the scenes.

### Avoid "easy" and "simple"

Expand Down

0 comments on commit 9323181

Please sign in to comment.