Skip to content

Latest commit

 

History

History
126 lines (78 loc) · 4.95 KB

docstyle.md

File metadata and controls

126 lines (78 loc) · 4.95 KB
Raw

SimCenter Documentation Style Reference

This reference is based on Purdue Owl, the Google developer documentation style guide and the Python documentation style guide. Some deviations and additions are indicated with footnotes.

This document is intended to provide a convenient reference, not a comprehensive guide. Pending the development of more extensive SimCenter guidelines, the resources mentioned above are recommended for guidance beyond what is provided here.

Text Formatting

Bold face

Use bold formatting for UI elements and at the beginning of notices. This includes names for buttons, menus, dialogs, windows, list items, or any other feature in the page or console that has a visible name.

Do not use code font for UI elements, unless it's an element that meets the requirements for code font. In that case, use both code font and bold.

Italics

Proper uses of italics:

  • Drawing attention to a specific word or phrase, such as when defining terms or using words as words.
  • Referring to titles of books, movies, web series, and other full-length works, unless they are part of a link.
  • Referring to parameter names. For example, when you refer to the parameters of a method like doSomething(Uri data, int count), italicize data and count.
  • Using mathematical variables.

Some improper uses of italics:

  • Names of mathematical functions, operators, or units; use the Latex commands \mathrm or \operatorname appropriately to avoid improper italics when writing mathematical expressions.
Underlining (Don't underline)

Don't underline.

Code (Monospace) font

Apply a monospace font to code in text, file names, inline code, and user input.

Use code blocks for code samples or other blocks of code. Do not override or modify font styles inline. Use code font to mark up code, such as class names, method names, HTTP status codes, console output, and placeholder variables.

Capitalization

Use American English style for general capitalization. When possible, use sentence case in low-level headings, titles, and navigation.

Quotation marks

In general, use American English style when punctuating quotations. For titles of shorter works-such as articles or episodes in a web series-put titles in quotation marks, unless they are part of a link.

Numbers

Spell numbers out

  • Numbers from zero through nine, except as noted below in Numbers as numerals.

  • A number that starts a sentence.

    Exception: It's okay, but non-optimal, to begin a sentence with a four-digit year.

  • A number that is followed by a numeral (e.g. "This procedure creates fifteen 100,000-byte files.").

  • Indefinite and casual numbers (e.g. "The API might return a list of a million songs").

Use numerals

  • Numbers 10 and greater.

    Exceptions: Always use numerals for the following items, even if they are less than 10:

    • Version numbers.
    • Technical quantities, such as amounts of memory, amounts of disk space, numbers of queries, or usage limits.
    • Page numbers.
    • Chapter numbers, sections, pages, and so on.
    • Prices.
    • Numbers without units, such as numbers used in mathematical expressions.

  • Numbers less than 10 when they appear in the same sentence with numbers greater than 9. For example, "The menu contains 15 options but 6 of them are disabled".

  • Negative numbers.

  • Most fractions.

  • Percentages.

  • Dimensions.

  • Decimals.

  • Measurements.

  • Numbers in a range.

Fractions

  • Express fractions as decimal numbers, when possible.
  • When expressing fractions as words, connect the numerator and denominator with a hyphen unless one of them is already hyphenated.

Punctuation

  • Don't use ampersands (&) as conjunctions or shorthand for and. Use and instead. That includes headings and navigation.

    Exception: It's okay to use & in cases where you need to refer to a UI element or the name of a menu that uses &.

  • Put quotation marks and end punctuation outside of link text.