Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

Spelling

General information

The authoritative style guide for writing official text for TYPO3 is The TYPO3 Writing Style Guide on typo3.org.

Important

We use different title capitalization from the content style guide, to ease contribution. The main differences are explained below in Rules for titles & section headers.

This section aims to add some additional explanations and more examples for rules already defined in the style guide. It also explains how to apply the rules in the documentation (for example format with reST).

Since the English language is not always specific and there may be more than one correct spelling for some words, we have added a Spelling, terms and glossary. If something is not mentioned here specifically, use correct spelling in English language or rather American (US) language. Refer to the resources, which the style guide suggests, or use Merriam Webster (https://m-w.com) as last resort. If in doubt, ask in Slack channel #typo3-documentation (see Help & Support).

Rules for titles & section headers

We use "sentence case" for title case:

The first word is capitalized.
All other words are spelled as they would be spelled elsewhere: Proper nouns are capitalized, all other words written in lowercase.

This is different from the content style guide where more words are capitalized (first and last word, all words with 4 letters and more, all principal words).

This was changed on February 4, 2020 for the following reasons:

Sentence case is easier to follow for occasional contributors and developers
It is already being used intuitively by contributors most of the time. If the other title capitalization were enforced, a number of PR would have to be corrected as they come in.
Most of the documentation is spelled this way

This means, the same rules as in Rules for plain text apply to the titles.

For discussion, see Title capitalization in the docs (revisited)

Examples:

"TYPO3 is always spelled TYPO3"
"Using TypoScript"

Important

This applies to all headers on a page, not just the top level header (title).

In reST, headers are created by underlining / overlining with (====, ----, etc.) as described in Headlines and sections:

=================
This is the title
=================

This is the subheader
=====================

Rules for buttons & links

The same spelling rules as in the title apply to buttons and links.

Rules for referring to GUI elements

If the text refers to terms used in the GUI (for example a clickpath for selecting something from the menu is described), the spelling used in the GUI should be used, for example "File > Open" or "click on "ADMIN TOOLS > Extensions".

See Referring to GUI elements for information about how to use reST markup for this.

Rules for plain text

Rules for compound words

Compound words (or compounds) are words that have been glued together from one or more separate words to create a new term with a new meaning as in backyard (back and yard) or New Age (new and age).

But how should they be spelled? Backend, back-end or back end? Site package or sitepackage?

All these spellings for backend are currently correct spellings (at least according to some sources.

Important

In the TYPO3 context we have defined backend to be the preferred spelling, as well as sitepackage.

If a spelling has been explicitly defined in the Spelling, terms and glossary, please use that spelling.

How can you decide for yourself in other edge cases?

Tip

If in doubt, use what is commonly used in the documentation. If you see inconsistencies between documentation and English dictionaries or within the documentation, raise the issue in Slack.

Capitalization rules (plain text)

If a word has special spelling, for example a special TYPO3 word like TypoScript or an acronym like PHP, this spelling is applied.
Proper nouns and brand names are capitalized, for example Docker.
Most other words begin with a lowercase letter.

There are some edge cases and some terms are not spelled consistently throughout various resources. Often it also depends on the context. Capitalization may change over the course of time, for example see The Associated Press style guide will no longer capitalize 'internet'. In other texts, "internet" is still capitalized.

For this reason we have put together a spelling reference to list some common terms that may be difficult to spell or that are spelled differently in the TYPO3 context.

Exceptions for specific TYPO3 spellings

There are some specific TYPO3 spellings like TypoScript, TSconfig, stdWrap, ViewHelper, TYPO3, etc. These should be used! See Spelling, terms and glossary for more examples.

Exceptions for words taken from source code

If you are using class names, function names, databases tables or fields, configuration options etc, use the spelling that is used in the source code.

Examples:

function names in Connection
configuration options in Default soft reference parsers

Acronyms

Often acronyms are written with capital letters only. If terms are commonly spelled that way, this is how we spell them as well, for example HTML, CMS, PHP or LTS.

Proper names, brand names

General rules of the English language apply here:

If proper names or brand names (for example Coca-Cola) are used in normal text (not headlines), they are capitalized.

These can be countries, names of people, corporations or brand names.

Examples:

"This manual is designed to be readable by someone with basic UNIX command-line skills, but no previous knowledge of Git.": Git is capitalized, because it is a brand name (quote from Git User Manual)
Wikipedia
Europe

Tools with executables

Some tools have a program, which you can run. For example, Git has the command line tool git. When the documentation explicitly refers to the command git, its appropriate spelling is used, which is lowercase. In all other cases, we use capital spelling for Git, because it applies to the rules for Proper names, brand names.

The same goes for Docker, Composer, etc.

Spelling & preferred terms reference

The content was moved to Spelling, terms and glossary.

Used resources

In addition to the TYPO3 Content Style Guide, some other resources have been used:

Microsoft Writing Style Guide
"Don't use the same word for 2 different meanings", see RACKSPACE DEVELOPER DOCS: Use consistent terminology
Microsoft style guide

Capitalization:

"The tendency towards lowercase, which in part reflects a less formal, less deferential society, has been accelerated by the explosion of the internet.", Guardian and Observer Styleguide, look under "capital". Note that these are British publications and we use American spelling.
"When referring to GUI elements, match the capitalization used in the interface.", see IBM developerWorks editorial style guide
Stackexchange: Proper capitalization of commonly used acronyms
The Associated Press style guide will no longer capitalize 'internet'
Wikipedia: English capitalization of proper nouns
"A proper noun is a noun directly associated with an entity and primarily used to refer to that entity, such as London, Jupiter, Sharon, or Microsoft, as distinguished from a common noun, which is a noun directly associated with a class of entities (city, planet, person, corporation) and primarily used to refer to instances of a specific class (a city, another planet, these persons, our corporation)" (quote from Wikipedia: Proper Noun)
"[...] proper nouns are limited to single words only (possibly with the), while proper names include all proper nouns (in their primary applications) as well as noun phrases such as the United Kingdom, North Carolina" (quote from Wikipedia: Proper Names)

Compound words:

Wikipedia: English compound