Skip to content

Documentation style guide

Jump to bottom
Rand McKinney edited this page Aug 26, 2014 · 12 revisions

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.

##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, h4 for the next level. Avoid using h5 headings and lowever as it generally presents too many levels and is 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://localhose: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.

Clone this wiki locally