To Do
Glossary, Punctuation

Welcome to the OpenTTD Manual of Style. This document keeps the rules for all English in-game text (both of UK and US variants). This manual was first started with the goal of improving the text quality of the UI tooltips, as to make localization to different languages easier. Eventually this evolved into a full documentation project to unify in-game written-text rules, fix inconsistencies, and improve readability.

The OpenTTD Manual of Style is modeled after the Microsoft Writing Style Guide. Additional formatting unique to OpenTTD was sourced from community preferences or was taken from text already present in the original UI.

Scope

• Apply these rules only for text to be displayed in-game that is included in the OpenTTD core package.
• Code, images or any separate documentation included in the OpenTTD package will not follow the rules of this manual. If you wish to learn how to format code, please consult the OpenTTD Coding style guide available at the wiki.
• Text belonging to mods obtained through the in-game content downloader or anywhere else is not covered by this guide. It is however recommended for modders to follow these rules while creating new content as to keep consistency with the original texts.
• Text belonging to external readme files displayed on the in-game reader tool also falls out of the scope of this guide.

Quick reference guide

This is a summary of the most important rules for proofreaders to use as cheat-sheet when reviewing text. Be sure to read the entire style guide before starting revision as to clear any doubts.

• Language: use easy to understand terms and short sentences. Do not use jargon or slang.
• Language: use gender-neutral terms whenever possible.
• Capitalization: Use sentence style capitalization by default.
• Capitalization: Use title capitalization on vehicle names, resources, currencies, locations, building names, given names, ranks, applications, and keyboard shortcuts.
• Formatting: paragraphs consisting of more than one sentence will always end in a period or other end-of-sentence mark.
• Tooltips: always leave a paragraph break between a tooltip title and description, and put a colon at the end of the title. If a tooltip only has a title, put no punctuation at the end.
• Tooltips: never put a title on a tooltip belonging to a button with text (the text of the button is itself the title).
• Tooltips: always put a title on an icon button.

Language style

• The language style used in OpenTTD will be simple and precise.
• In-game text will favor small paragraphs and short sentences as to better convey information to all levels of English speakers.
• OpenTTD is a game about transportation networks like those of real-life societies, so technical vocabulary will be present, but not used in excess.
• Jargon and slang will not be used at all.
• The intention is to create textual content that is simple and relaxing to read, but also capable of easily passing complex information to anyone playing the game.

Bias-free communication

Because OpenTTD is played by many people across the globe, the language employed must be as inclusive as possible. Here are the key guidelines for bias-free communication.

• Avoid gendered pronouns like he or she.
• If referring to the player, always try to use sentence structures that address players as "you".

Correct	You can host a game via the multiplayer screen.
Incorrect	A user can host a game via the multiplayer screen.

• Use gender-neutral alternatives for common terms. Some examples below.

Use this	Not this
chair	chairman
workforce, staff	manpower
operates	mans

• Avoid references to sensitive political topics and mentioning geographical locations that are disputed.
• Do not use slang or profane/offensive language.
• When addressing players with disabilities avoid language that might appear patronizing such "suffering from" or "affected by".

Descriptive texts and UI labels

The OpenTTD UI is populated with text in two main formats with unique rules of their own: descriptive texts and UI labels.

Descriptive texts

Tooltips are an example of descriptive texts.

• Texts used to describe or provide in-depth information about a particular function, situation or concept of the game.
• Examples of descriptive texts are tooltips, newspaper messages, instructions or contextual tips and queries within the game.
• Descriptive texts will make use of one or more full sentences, which start with a capital letter on the first word. If a paragraph consists of more than one sentence, these will always end in a period or other end-of-sentence mark.

UI labels

Some examples of UI labels: field and button labels.

• UI labels are text that is used to simply name a particular function or field.
• Mostly employed for naming parts of the UI such as buttons, window frames, and table fields.
• UI labels will generally not form full sentences and never end with a period. They may sometimes end with a colon if introducing a dynamic field such as a number.
• UI labels should not be confused with tooltip titles; even if they look similar when used alone, tooltip titles are in practice descriptive texts.

Acronyms

Using acronyms is often a popular choice for making texts easier to read or for saving space in the UI. Some acronyms are widely understood and sometimes preferred over the terms they represent, but others may cause confusion to people who aren't familiarized with them. Keep in mind the following guidelines when using acronyms:

• By default, write acronyms in all uppercase.

Correct	If you have any doubts check our FAQ.
Incorrect	If you have any doubts check our Faq.

• In descriptive texts, well-recognized acronyms such as FAQ and UI and can be introduced without being spelled out.
• If you're in doubt if an acronym is widely recognized, you can check the American Heritage Dictionary to see if it's included in the list of common acronyms.
• Don't create new acronyms by yourself. If you feel a certain term should be made into a new acronym, consult with other developers first.
• In descriptive texts, spell-out unfamiliar technical acronyms when used the first time along with the acronym in brackets.

Correct	The Dash is a diesel multiple unit (DMU) available from 1984.
Incorrect	The Dash is a DMU available from 1984.

• Use lowercase on spelled-out acronyms unless it's a proper noun or a protocol.
• If an acronym is spelled in a mix of upper and lowercase for style reasons (such as BaNaNaS) check if this is the most common way of writing the acronym before doing so.

Correct	BaNaNaS is the content downloader for OpenTTD.
Incorrect	BANANAS is the content downloader for OpenTTD.

• Do not stylize existing acronyms on your own.
• For acronyms that have been assimilated into the english language (such as laser), write them entirely in lowercase as they are to be treated as common nouns.

Capitalization

Rules for capitalization determine the use of capital letter within written text. They help improve how the text reads and how it looks.

General capitalization rules

Follow these base guidelines when capitalizing texts:

• Use sentence capitalization by default on both descriptive texts and UI elements.
• Always capitalize the first word of a new sentence, phrase or label. Rewrite the ones that start with a word that's mandatorily lowercase (such as a stylized acronym).

Correct	The eGRVTS is a newgrf vehicle set by Zephyris.
Incorrect	eGRVTS is a newgrf vehicle set by Zephyris.

• Don't use all uppercase for emphasis on words. Rephrase if necessary.

Correct	You can download OpenTTD on the link below.
Incorrect	You can download OpenTTD HERE.

• Don't use internal word capitalization unless it's an acronym, a proper noun, or a product name.

Correct	You can check our email address in the contacts section.
Incorrect	You can check our eMail address in the contacts section.

• Don't capitalize spelled-out acronyms unless it contains a proper noun.

Correct	The electric multiple unit (EMU) is a type of train.
Incorrect	The Electric Multiple Unit (EMU) is a type of train.

Capitalization styles

There are two types of capitalization used in interface texts for OpenTTD, sentence and title capitalization.

Sentence capitalization

• Always capitalize the first word, whether the text is a phrase, sentence, heading or label.
• Always capitalize proper nouns.
• Always capitalize the first word of titles.
• Every other remaining words should be written entirely in lower case save for instances covered by different capitalization rules.

Example (prompt text)

Are you sure you want to exit OpenTTD and return to Unix?

• General descriptive text.

Example (tooltip)

Start playing on a new map.

• General UI label text.

Example (button)

New game

• Headings.

Example

Section 1 - How to play

• Tooltips.

Example

Build railway station: For loading and unloading cargo or passengers.

• Window titles.

Example

Operating profits graph

Title capitalization

• Always capitalize first and last words of a phrase or sentence, heading or label.
• Do not capitalize articles, prepositions or conjunctions unless they are the first or last words of a phrase or sentence.
• Capitalize all other words in a phrase, sentence, heading or label, including verbs, nouns, adverbs, adjectives, and pronouns.
• If words are joined by a hyphen capitalize them as if they were separated by a regular space.

Example (title)

OpenTTD Scenario Editor

• Resource names and energy types when used as items in a list.

Example 1	Station accepts: Coal, Iron Ore, Goods
Example 2	Engine type: Diesel

• Product/Vehicle names.

Example

Kirby Paul Tank

• Country/Nationality/Coin names.

Example

Yen, Dollar, Euro

• Geographical locations and structure names.

Example

Wartington Coal Mine

• App within App names

Example

Jazz Jukebox

• Company names.

Example

Burnley & Smiths Inc.

• Given names and ranks.

Example

Chief Executive Officer

• Keyboard shortcuts.

Example

Ctrl+Click+Drag to select an area

Formatting

Descriptive texts

General descriptive text formatting

• Use sentence style capitalization by default.
• Use center alignment in tooltips, news, messages and information windows.
• Use left alignment in everything else.

Headings

Headings are used to name documents and to separate them into sections. They are a form of internal organization in written text. Follow these guidelines when formatting headings:

• Use sentence capitalization.
• Never end headings with a period or any other punctuation unless it's an exclamation or question mark used for emphasis.

Correct	1 - What's new
Correct	1 - What's new?
Incorrect	1 - What's new.

Key names and shortcuts

These are compound terms that indicate one or a combination of keys and mouse actions used to perform game functions without using interface buttons. Follow these guidelines when writing key names and shortcuts:

• Use title capitalization.
• If a shortcut requires more than one action to perform, separate them by using a plus sign (+) instead of a space.

Correct	Ctrl+Click+Drag selects the area diagonally.
Incorrect	Ctrl, Click and Drag selects the area diagonally.

Titles

Titles refer to names of individual works (books, songs, apps, articles, etc). Follow these guidelines when formatting titles appearing in-game:

• Apps - use title capitalization.

Example 1	Jazz Jukebox
Example 2	OpenTTD Scenario Editor

• Documents or books - use title capitalization.

Example

OpenTTD Manual of Style

• References of chapters or sections - if a chapter name is referred to in descriptive texts, enclose chapter name in quotation marks and use sentence capitalization as if it was a new sentence.

Example

For more information see section 9 "How to play".

• Song names - use title capitalization.

Example

Playing song 1 - Taxi Ride

Tooltips

Elements of a tooltip: Green - title; red - description; blue - additional shortcuts.

Tooltips are texts printed in small pop-up windows that appear when you hover the mouse cursor over certain UI functions. They are a large part of the OpenTTD descriptive texts. Tooltips can be composed by one or more of three possible parts:

• Title - the name of function or tool
• Description - a short explanation of the function or tool
• Additional shortcuts - Text informing of additional functions unlocked by key combinations ("Ctrl+Click+Drag selects an area")

The following general formatting rules are applied to tooltips:

• Depending on the contents present, the tooltip text will always follow this order - title, description, additional shortcuts.
• A title will always be separated by a colon and a paragraph break if followed by a description or additional shortcuts.
• Do not insert any other paragraph breaks aside from the one separating the title.
• A tooltip without a title must always contain a description. It can never have additional shortcuts alone.

Buttons with icons tooltips

If a tooltip is associated with an icon button the following rules apply:

• Icon button tooltips must always have a title.

Icon button tooltips always require a title on the first line.

Buttons with text tooltips

If a tooltip is associated with a text button the following rules apply:

• Text button tooltips must never have a title, as it is already written on the button itself.
• Text button tooltips must always have a description.

A text button tooltip. The button label acts as a title.

Table tooltips

If a tooltip is associated with a table the following rules apply:

• If a table has a title, the associated tooltip must have no title. If a window only contains a single table, the window title is also the table title.
• If a table doesn't have a title, the associated tooltip must always have a title.

If a table has a title or does not share a window with other tables, then the tooltip requires a description only.

UI labels

General UI label formatting

• Use center alignment in normal buttons and window titles.
• Use left alignment for buttons that generate a dropdown selection.
• Use left alignment for all other UI labels.

Numbers

General formatting rules for numbers

Follow these base guidelines when writing numbers:

• In descriptive texts, never start a sentence with a numeral. Rephrase otherwise.

Correct	One bus is all that is necessary to start a simple passenger route between two stops.
Incorrect	1 bus is all that is necessary to start a simple passenger route between two stops.

• Spell out numbers from one to nine in descriptive texts by default, unless the number is part of a proper noun (such as a company name).

Correct	Places a section of rail in one direction.
Correct	View finances for 4-Rail Inc.
Incorrect	Places a section of rail in 1 direction.

• When a descriptive text refers to multiple numbers that relate to each other, always use numerals even if the numbers are below ten.

Correct	There are 15 trains, followed by 5 trains, followed by 1 train.
Incorrect	There are 15 trains, followed by five trains, followed by one train.

Numerals

Use numerals (not spelled out) in the following instances:

• Measurement units, dimensions, and mathematical formulas.

Example

Max. speed: 100 km/h

• References to keys or in-game values/amounts.

Example 1	5 units of coal
Example 2	Press key 4

• Percentages.

Example

It takes 5% of the total value.

• Numbered sections such as pages and chapters.

Example

Page 5, Chapter 1

Ordinals

• By default, always spell out ordinal numbers.

Correct	If this is the first time playing OpenTTD, check out the manual.
Incorrect	If this is the 1st time playing OpenTTD, check out the manual.

• If referring to dates never spell out ordinals.

Correct	3rd Mar 1982
Correct	The 20th century
Incorrect	The twentieth century

Writing

General writing tips

• Use simple terms and privilege simple and short sentences.
• Be accurate and precise. Pick words that are easy to understand and describe exactly what you need.

Preferable (tooltip)	Places a railway bridge over land or water.
Avoid (tooltip)	Constructs a railway bridge over land or water.

• Don't use complex jargon.
• Don't use slang or profane language.

Tooltips

• In a tooltip description avoid phrases that point to the activation of the tool itself unless absolutely necessary or if referring to key shorcuts.

Preferable	Demolish: Clears all objects in a selected area. Ctrl+Click+Drag selects the area diagonally.
Avoid	Demolish: Use this tool to clear all objects in an area. Ctrl+Click+Drag selects the area diagonally.

• In a tooltip description do not repeat information that is already present on the title or the button text. If you can't avoid redundancy, rephrase or detail the description so it reads differently.

Correct	Build canals: Places a navigable waterway on flat land.
Incorrect	Build canals: Places a navigable canal on flat land.

• If a tooltip title fully describes a tool by itself, do not write a description.

Correct	Pause game
Incorrect	Pause button: Pauses the game.

• In a tooltip description, always describe functions in the present tense, using either 2nd or 3rd person form without using pronouns.

Example 1	Build road: Places a section of road in a single direction.
Example 2	Build road: Place a section of road in a single direction.

• In a tooltip title don't use the word "and". Replace it with an ampersand (&).

Correct	Music & sound
Incorrect	Music and sound

• When writing additional shorcuts, always use one sentence per function.

Correct	Ctrl+Click+Drag selects an area. Shift+Click shows price preview.
Incorrect	Ctrl+Click+Drag selects an area, and Shift+Click shows price preview.

UI labels

• Always try to write UI labels text using as few words as possible.
• In button labels don't use the word "and". Replace it with an ampersand (&).

Correct	Save & quit
Incorrect	Save and quit

• Don't repeat information that's already on a title or better detailed on a tooltip.