You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: page/style-guide.md
+62-76Lines changed: 62 additions & 76 deletions
Original file line number
Diff line number
Diff line change
@@ -10,10 +10,7 @@ customFields:
10
10
11
11
## Formatting Conventions
12
12
13
-
Articles in the learn site are authored with [GitHub Flavored
14
-
Markdown](http://github.github.com/github-flavored-markdown/), and
15
-
the beginning of each article contains some [YAML](http://www.yaml.org/)
16
-
"front matter" that contains metadata used when the article is published.
13
+
Articles in the learn site are authored with [GitHub Flavored Markdown](http://github.github.com/github-flavored-markdown/), and the beginning of each article contains some [YAML](http://www.yaml.org/) "front matter" that contains metadata used when the article is published.
17
14
18
15
### Article Header Metadata
19
16
@@ -30,104 +27,93 @@ attribution:
30
27
---
31
28
```
32
29
33
-
The `source` and `atttribution` properties are optional, and should be used
34
-
primarily if you are importing an article from an outside source where it was
35
-
published before being donated for inclusion in the learn site. You should **not**
36
-
include these properties if you are adding a new article or editing an existing
37
-
one, as your contribution will be acknowledged via the git commit logs.
30
+
The `source` and `attribution` properties are optional, and should be used primarily if you are importing an article from an outside source where it was published before being donated for inclusion in the learn site. You should **not** include these properties if you are adding a new article or editing an existing one, as your contribution will be acknowledged via the git commit logs.
38
31
39
32
### Code Blocks
40
33
41
-
Code blocks should be set off with triple backticks and should **not** be
42
-
indented. (That is to say, the site prefers the use of "fenced blocks"
Code blocks should be set off with triple backticks and should **not** be indented. (That is to say, the site prefers the use of "fenced blocks"notation supported by [gfm](http://github.github.com/github-flavored-markdown/).)
45
35
46
36
## Writing Style
47
37
48
-
Content should be educational and accessible to a broad audience of developers.
49
-
The primary target audience is beginning to intermediate jQuery users, with
50
-
advanced jQuery users as a secondary audience. When creating content for this
51
-
site, please keep one of these audiences in mind as well as the following style
52
-
guidelines.
38
+
Content should be educational and accessible to a broad audience of developers. The primary target audience is beginning to intermediate jQuery users, with advanced jQuery users as a secondary audience. When creating content for this site, please keep one of these audiences in mind as well as the following style guidelines:
53
39
54
40
### Prose & Grammar
55
41
56
-
- Use the Oxford comma in a list of three or more items:
57
-
-**Yes:** The `load`, `scroll`, and `error` events (e.g., on an `<img>` element) do not bubble.
58
-
-**No:** The `load`, `scroll` and `error` events (e.g., on an `<img>` element) do not bubble.
59
-
- Numbers:
60
-
- Spell out numbers one under 10.
61
-
- Use numerals for numbers 10 and above.
62
-
- Abbreviations:
63
-
- Spell out abbreviated words on first reference, followed by the abbreviation in parentheses. Use abbreviations on second reference.
42
+
- Use the Oxford comma in a list of three or more items:
43
+
- **Yes:** The `load`, `scroll`, and `error` events (e.g. on an `<img>` element) do not bubble.
44
+
- **No:** The `load`, `scroll` and `error` events (e.g. on an `<img>` element) do not bubble.
45
+
- Numbers:
46
+
- Spell out numbers below 10 (e.g. one, two, three)
47
+
- Use numerals for numbers 10 and above (e.g. 10, 20, 100).
48
+
- Abbreviations:
49
+
- Spell out abbreviated words on first reference, followed by the abbreviation in parentheses. Use abbreviations on second reference.
64
50
65
-
#### Code within Prose
51
+
#### Code Within Prose
66
52
67
-
- Always use a `code` tag to denote code from prose.
68
-
- Properties: use a dot, followed by the property name, e.g.:`.length`.
69
-
- Functions: use the function name, followed by parentheses, e.g.:`myfunction()`.
70
-
- Methods: use a dot, followed by the method name, followed by parentheses, e.g.: The `.focus()` method is a shortcut for the `.bind('focus', handler)` in the first and second variations, and `.trigger('focus')` in the third.
53
+
- Always use a `code` tag to denote code from prose.
54
+
- Properties: use a dot, followed by the property name, e.g. `.length`.
55
+
- Functions: use the function name, followed by parentheses, e.g. `myfunction()`.
56
+
- Methods: use a dot, followed by the method name, followed by parentheses, e.g. The `.focus()` method is a shortcut for the `.bind( "focus", handler)` in the first and second variations, and `.trigger( "focus" )` in the third.
71
57
72
58
#### Article & Sentence Structure
73
59
74
-
- Use headings to break up content into easier-to-read sections. Begin headings within an article with `<h2>`.
75
-
- Keep sentences short and to the point. A good rule-of-thumb is to break up any sentence longer than 21 words into two or more seperate thoughts.
76
-
- Lists:
77
-
- Use bulleted lists when necessary to share a series of five or more points.
78
-
- Use numbered lists only when providing step-by-step instruction - note that this should be avoided.
79
-
- Use a period at the end of each ordered list item, and a period or comma at the end of an unordered list item.
60
+
- Use headings to break up content into easier-to-read sections. Begin headings within an article with `<h2>`.
61
+
- Keep sentences short and to the point. A good rule-of-thumb is to break up any sentence longer than 21 words into two or more seperate thoughts.
62
+
- Lists:
63
+
- Use bulleted lists when necessary to share a series of five or more points.
64
+
- Use numbered lists only when providing step-by-step instruction – note that this should be avoided.
65
+
- Use a period at the end of each ordered list item, and a period or comma at the end of an unordered list item.
80
66
81
67
#### Spelling
82
68
83
-
- Use standard American English spelling.
84
-
- Capitalization:
85
-
- Capitalize all proper nouns.
86
-
- Do not capitalize HTML elements in code examples.
87
-
- Capitalize all words in a heading or sub-heading with the exception of article adjectives and the prepositions like "with," "of," or "to."
88
-
- Capitalize the first word in a list.
89
-
- Punctuation:
90
-
- Periods and commas go inside quotation marks.
91
-
- Avoid using semicolons.
69
+
- Use standard American English spelling.
70
+
- Capitalization:
71
+
- Capitalize all proper nouns.
72
+
- Do not capitalize HTML elements in code examples.
73
+
- Capitalize all words in a heading or sub-heading with the exception of article adjectives and the prepositions like "with," "of," or "to."
74
+
- Capitalize the first word in a list.
75
+
- Punctuation:
76
+
- Periods and commas go inside quotation marks.
77
+
- Avoid using semicolons.
92
78
93
79
#### Pronoun Usage
94
80
95
-
- Don't use "I," "me," "us," "our," "we," and gender-specific pronouns such as "him" or "she."
96
-
- Use the second-person pronoun "you" when addressing the reader, and the definite article "the" when addressing code or content:
97
-
-*"You will be able to foo bar after you bar the foo."*
98
-
-*"Insert the paragraph after the unordered list."*
81
+
- Don't use "I," "me," "us," "our," "we," and gender-specific pronouns such as "him" or "she."
82
+
- Use the second-person pronoun "you" when addressing the reader, and the definite article "the" when addressing code or content:
83
+
- *"You will be able to foo bar after you bar the foo."*
84
+
- *"Insert the paragraph after the unordered list."*
99
85
100
86
#### Voice & Tone
101
87
102
-
- Do write in clear, easy-to-understand statements.
103
-
- Do write in active voice.
104
-
- Do keep the audience in mind while writing.
105
-
- Do write conversationally.
106
-
- Do write in the second person to address the reader.
107
-
- Do use the imperative mood.
108
-
- Do use humor strategically. When in doubt, err on the side of formality.
109
-
- Do use hyperlinks to refer readers to concepts or topics that have been covered in other sections.
110
-
- Do attribute others.
111
-
- Don't assume the reader will have prior knowledge of topics or concepts, especially when targeting beginner or intermediate audiences.
112
-
- Don't use rhetorical questions.
113
-
- Don't write in first or third person.
88
+
- Do write in clear, easy-to-understand statements.
89
+
- Do write in active voice.
90
+
- Do keep the audience in mind while writing.
91
+
- Do write conversationally.
92
+
- Do write in the second person to address the reader.
93
+
- Do use the imperative mood.
94
+
- Do use humor strategically. When in doubt, err on the side of formality.
95
+
- Do use hyperlinks to refer readers to concepts or topics that have been covered in other sections.
96
+
- Do attribute others.
97
+
- Don't assume the reader will have prior knowledge of topics or concepts, especially when targeting beginner or intermediate audiences.
98
+
- Don't use rhetorical questions.
99
+
- Don't write in first or third person.
114
100
115
101
#### Linking & Referencing Content
116
102
117
-
- Link to relevant content within the learn.jquery.com site to refer readers to previously covered topics or concepts.
118
-
- Link to the jQuery blog or API documentation when necessary.
119
-
- Use inline hyperlinks to reference relevant content.
120
-
- Acceptable external resources:
121
-
-Mozilla Developer Network
122
-
-Webplatform.org
123
-
-htmldog.com
103
+
- Link to relevant content within the learn.jquery.com site to refer readers to previously covered topics or concepts.
104
+
- Link to the jQuery blog or API documentation when necessary.
105
+
- Use inline hyperlinks to reference relevant content.
0 commit comments