经验感悟编程经验

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 write in the second person to address the reader.
  • 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.

Linking & Referencing Content

  • 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.
  • Follow all style guides for your code examples.
分享到