Typography

Case

Use title case for proper names, e.g. Python, C#, WebSocket, GitHub. Among the notable exceptions are macOS, q and kdb+.

The language is q. The database, process and product are all known as kdb+. Although both are proper names they are both set in lower case, except where they begin sentences or headings.

Headings

Set headings in sentence case, i.e., in lower case except for

  • the first letter
  • acronyms, e.g. IPC, HTTP, API
  • proper names, e.g. Python, C#, WebSocket, GitHub, macOS

Minimise punctuation within a heading and end it without punctuation.

Number headings in an article only when there are many references in the text to the numbers. Where there are a few references to heading numbers, replace them with the italicised heading texts, linked to the headings.

Ordered and unordered lists

Use numbered lists only

  • where it is necessary to refer to a list item, e.g. “as in (3) above”
  • where the order is significant, e.g. in a sequence of instructions

Where

  • a list has no more than five items;
  • the items are short;
  • its items are clauses of a single sentence

suffix all but the last item with a semicolon, as in this sentence. Otherwise, leave the ends of list items unpunctuated.

Admonitions

Use admonitions for warnings, tips and notes.

Example

This shows how it’s done.