The authoritative style guide for writing official text for TYPO3 is The TYPO3 Writing Style Guide on typo3.org.
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 (e.g. 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 reference, preferred terms & 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)
- “TYPO3 is always spelled TYPO3”
- “Using TypoScript”
This applies to all headers on a page, not just the top level header (title).
In reST, headers are created by underlining / overlining with (
as described in Headlines and Sections:
================= This is the title ================= This is the subheader =====================
Rules for referring to GUI elements¶
If the text refers to terms used in the GUI (e.g. a clickpath for selecting something from the menu is described), the spelling used in the GUI should be used, e.g. “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.
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 reference, preferred terms & glossary, please use that spelling.
How can you decide for yourself in other edge cases?
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, e.g. a special TYPO3 word like TypoScript or an acronym like PHP, this spelling is applied.
- Proper nouns and brand names are capitalized, e.g. 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 reference, preferred terms & 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.
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 (e.g. Coca-Cola) are used in normal text (not headlines), they are capitalized.
These can be countries, names of people, corporations or brand names.
- “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)
Tools With executables¶
Some tools have a program, which you can run. For example, Git has the command line
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 reference, preferred terms & glossary.
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
- “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)