Documentation style guide

The purpose of this style guide is to make sure that anyone authoring documentation writes in a clear and unified way that reflects a common style. This guide is intended to be prescriptive but not onerous and is open to community contribution and discussion.

NOTE: The current expressjs.com site may not adhere to these guidelines, but:

• The intent is to update the site to conform to them.
• New material should be conforming as much as possible.

See also: Node.js doc style guide.

Headings

Use sentence case for headings. Basically, capitalize the first word; other words are only capitalized if they would normally be capitalized in a sentence.

Use h2 tags for top-level headings, and h3 for the next level of sub-headings, and h4 for the next level. Avoid using h5 headings and lower as that generally presents too many levels and its often better to reorganize. However, if you cannot avoid, there is no strict prohibition from using them.

NOTE: The site currently uses h3 tags for top-level heads. We'll correct this ASAP.

Formatting conventions

File names, code literals, routes

Enclose the following in <code> tags so they are rendered inline in fixed-pitch font:

• File names and directory paths; for example package.json.
• Code elements when used inline, for example object names, function calls, and the like; for example app.route().
• URLs and routes, for example http://localhost:8000 or /birds/about.

Code samples

Code samples longer than one line should be put within a +js tag to provide syntax highlighting:

  +js.
    code goes here...

Lists

Use numbered lists only when the order of the items is important; for example, the steps in a procedure:

1. Step one.
2. Step two.
3. And so on.

Use bullet lists (unordered lists) for three or more items when the order is not significant; for example:

Lists:

• Are easier to read than big blocks of text.
• Make items stand out.
• Clearly identify parallel items.

Do not use bullets simply to start a regular paragraph.

Capitalize list items. End each item with a period only when ending a sentence, such as:

• In this example.
• In this other example.
• In this final example.

Never end a list item with a comma, semicolon, or colon.

Notes, Warnings, and Related Information

NOTE: The specific CSS for these items are TBD.

Use special div blocks to call out text for these items, for example:

<div class="note">NOTE: Blah blah blah.</div>
<div class="warning">NOTE: Blah blah blah.</div>
<div class="related">NOTE: Blah blah blah.</div>

Spelling, grammar, and usage

Use American spelling and grammar: "behavior" instead of "behaviour," "color" instead of "colour," and so on.

Collective nouns, such as corporations, are singular, not plural:

• CORRECT: StrongLoop is a company based in California (standard American usage).
• INCORRECT: StrongLoop are a company based in California (standard British usage).

In lists of three or more items, use the serial comma.

Spell out acronyms and abbreviations upon first use, with the acronym in parenthesis. For example:

This enables you to create a service-oriented architecture (SOA).

Do not use Latin abbreviations, which may not be understood by all readers. Instead use the English equivalent:

• Instead of "i.e." use "that is".
• Instead of "e.g." use "for example".
• Instead of "etc." use "and so on".

Put punctation inside quotation marks when they appear. For example:

Use American spelling and grammar: "behavior" instead of "behaviour," "color" instead of "colour," and so on.

EXCEPTION: If the item within the quotes is a literal such as used in keystroke entry, or if the meaning would otherwise be unclear, put the comma outside of the quotation mark. For example:

At the prompt enter "Y", then hit Enter.