Writing Style Guide

General Assumptions

Buttons

Buttons are capitalized using Title Case.

Commas in Lists

We use the so-called Oxford (or serial) comma, setting a comma before the final “and” or “or” in a list with three or more items.

Currency

Currency values are written using the three-letter ISO code, followed by a space, followed by the value written according to our number style.

Currency symbols, such as € and $ can be used as a shortened form. They are placed in front of the value, with no space separating them.

Dashes

We use an em-dashes without spaces around to mark parenthesis. We use n-dashes without spaces around to mark from–to in a number series.

Dates

We prefer the international date style: day, month, and year. We always write the month name. Dates written as numbers only will cause confusion for our international audience. Years are always written in four digits.

Month names are normally written in full, but can be abbreviated if you lack space, as rendered by the PHP function date('M.'): Jan., Feb., Mar., Apr., May., Jun., Jul., Aug., Sep., Oct., Nov., and Dec.

Extensions

All extensions have a proper name in addition to the lowercase extension key. For example:

• Name: AWS SDK for PHP
• Key: aws_sdk_php

When we write about extensions, we use the proper name with the convention: "The [proper name] extension...".

On the first instance of the extension name in the text, we include the key in paranthesis immediately following the proper name. For example, "The AWS SDK for PHP (aws_sdk_php) extension...".

Where appropriate, on the first instance of the extension name in the text, we also include the link to the extension's page in the TYPO3 Extension Repository.

When we want to refer just to the key, for example in procedural or highly technical content, we prepend the key name with "EXT" in upper case, and we apply code formatting style to the text. For example, EXT:aws_sdk_php.

Numbers

Numbers are written using a dot “.” as a decimal separator and comma “,” as a thousands separator. We normally use max two decimals. The number of decimals used should reflect the text's need for accuracy.

The thousands separator can be omitted for numbers 1,000–9,999.

A zero should be included before the dot in numbers less than 1.0.

Very large integer numbers (those above 999,999) should be written using million, billion, or trillion, replacing the last six or nine digits.

Numbers less than ten are spelt out, unless they are dates or part of a list with larger values.

Emphasis

We use italics for emphasis on single words or compound words. Bold text is used to increase visibility on words, compound words, parts of sentences, and sentences. We never use underlined text.

Place Names

English spelling is used for placenames. When an English spelling is not available, the name is transliterated using the Unicode Transliteration Guidelines. Acceptable transliterations can be found on Wikipedia and OpenStreetMap's Nominatim Search

Keeping diacritics is preferred, but not required.

Place names should always be introduced with their country. State or region is optional, but recommended where it can avoid misunderstanding. When not otherwise explained in context, the country and state/region is postfixed, separated by comma(s): [Place Name], [State/Region, ][Country].

Names of states and regions are never abbreviated.

Quotes

Exact quotes are written between double quotation marks. Quotes within quotes are written between single quotes. For long quoted sections, we use indented block quotations without quotation marks. Periods and commas are placed within quotation marks. Colons and semicolons are placed outside of quotation marks.

Changes and omissions within quotes are [in brackets].

Title Case

We capitalize all principal words of a title, including the first and the last words. We do not capitalize articles, prepositions or conjunctions that have fewer than four letters, such as:

• a
• an
• and
• at
• but
• by
• for
• in
• nor
• of
• on
• or
• so
• the
• to
• up
• yet

To make things easy, use AP capitalization at capitalizemytitle.com, and be aware that we are using a somewhat simplified rule.