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.
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
- 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.
Use admonitions for warnings, tips and notes.
This shows how it’s done.