# Prose Style Guide

## Formatting Conventions

On many sites, prose (sites, README, docs, etc) is authored with GitHub Flavored Markdown. Some sites (e.g. api.jquery.com) use an XML-based markup system but the advice offered here for good writing still applies.

## Writing Style

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, please keep one of these audiences in mind as well as the following style guidelines:

### Grammar

• Use the Oxford comma in a list of three or more items:
• Yes: The load, scroll, and error events (e.g. on an <img> element) do not bubble.
• No: The load, scroll and error events (e.g. on an <img> element) do not bubble.
• Numbers:
• Spell out numbers below 10 (e.g. one, two, three).
• Use numerals for numbers 10 and above (e.g. 10, 20, 100).
• Abbreviations:
• Spell out abbreviated words on first reference, followed by the abbreviation in parentheses. Use - abbreviations on second reference.

### Code Within Prose

• Always use a code tag to denote code from prose.
• Properties: use a dot, followed by the property name, e.g. .length.
• Functions: use the function name, followed by parentheses, e.g. myfunction().
• Methods: use a dot, followed by the method name, followed by parentheses, e.g. The .focus() method is a - shortcut for .bind( “focus”, handler ) in the first and second variations, and .trigger( “focus” ) in the third.

### Article & Sentence Structure

• Use headings to break up content into easier-to-read sections. Begin headings within an article with <h2>.
• 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.
• Lists:
• Use bulleted lists when necessary to share a series of five or more points.
• Use numbered lists only when providing step-by-step instruction – note that this should be avoided.
• Use a period at the end of each ordered list item, and a period or comma at the end of an unordered list item.

### Spelling

• Use standard American English spelling.
• Capitalization:
• Capitalize all proper nouns.
• Do not capitalize HTML elements in code examples.
• Capitalize all words in a heading or sub-heading with the exception of article adjectives and the prepositions like “with,” “of,” or “to.”
• Capitalize the first word in a list.
• Punctuation:
• Periods and commas go inside quotation marks.
• Avoid using semicolons.

### Pronoun Usage

• Don’t use “I,” “me,” “us,” “our,” “we,” or gender-specific pronouns such as “him” or “she.”
• Use the second-person pronoun “you” when addressing the reader, and the definite article “the” when addressing code or content:
• “You will be able to foo bar after you bar the foo.”
• “Insert the paragraph after the unordered list.”

### Voice & Tone

• Do write in clear, easy-to-understand statements and in active voice.
• Do keep the audience in mind while writing.
• Do write conversationally.
• Do use the imperative mood.
• Do use humor strategically. When in doubt, err on the side of formality.
• Do use hyperlinks to refer readers to concepts or topics that have been covered in other sections.
• Do attribute others.
• Don’t assume the reader will have prior knowledge of topics or concepts, especially when targeting beginner or intermediate audiences.
• Don’t use rhetorical questions.
• Don’t write in first or third person.

• Link to relevant content within the learn.jquery.com site to refer readers to previously covered topics or concepts.
• Link to the jQuery blog or API documentation when necessary.
• Use inline hyperlinks to reference relevant content.
• Acceptable external resources:

### Code Examples

• Use examples to illustrate important concepts.
• Examples should indicate what the expected result will be in comments before code is presented.
• Break long examples up into shorter sections to aid comprehension.
• Favor “Right Way” examples over “Wrong Way” examples – there is more than one wrong way to do something, after all.
• Use good comments so that explanation within prose isn’t necessary.
• Test your code examples before submitting.