A manual of style for OpenTTD

[mcbanhas]

Hello,

I would like to share and ask feedback for something I've been working on. I joined the OpenTTD community a few months ago, and as someone who previously worked on localization for video games, I found the UI translation for my native language to be in a bit of a sorry state, and decided to volunteer as a translator to fix some of the more glaring problems.

However, upon delving deeper into translation work and having had a good look at the quality of the original English language texts, it turns out it is lacking some maintenance, and there are plenty of inconsistencies and formatting problems going around in the UI.

So I took it upon myself to work on a reformatting and rewriting of the English original UI texts. The first result of these efforts can already be found and tested on PR #7870.

One problem came up with this submission though, namely that the maintainers could not agree on a way to proofread or review the submission without having the lines split in multiple PRs, which in turn could difficult implementation.

Upon discussing this matter I came to an agreement with @LordAro that the best way to improve the status of the UI English text would be to first come up with a manual of style: a set of rules covering both grammar, formatting and wording to standardize the way texts are written in English (both US and UK variants) for OpenTTD. Any further edits and corrections would then be made and proofread by consulting this guide.

As of the moment I am the process of writing such a manual which then I will submit for approval, but I would like to hear your opinion on what should go. My textual fixes on PR #7870 were based on some of the more cohesive aspects of the current (unfixed) text, along with a string of opinions that I lifted from users on the IRC channel. Main changes are as it goes:


Capitalization:

Currently OpenTTD inconsistently uses Title Capitalization (first letter of all words capped) and Sentence capitalization (first letter of first word capped) on most of its UI elements. Initially I intended to change all to Title Capitalization, but most people seemed to prefer Sentence capitalization as it goes with more modern software texts standards, such as a the Microsoft style guide. As such my proposed changes are:

[+] Spoiler

General text: Sentence capitalization
Button text: Sentence capitalization
Field text (i.e "Income this year:..."): Sentence capitalization
Tooltips: Sentence capitalization
Window titles: Sentence capitalization

Resource names(Coal, Iron, etc): Title Capitalization
Product/Vehicle names: Title Capitalization
Country/Nationality/Coin names: Title Capitalization
App within App names (Jazz Jukebox, Scenario Editor): Title Capitalization (including text in buttons)
Company names: Title Capitalization
Given names/Ranks (i.e. Chief Executive Officer): Title Capitalization
Keyboard shortcuts (i.e. "Ctrl+Click+Drag"): Title Capitalization

Formatting:

There are numerous inconsistencies with formatting especially on the tooltip text. Some tooltips contain a title for the tool they describe, while others only contain descriptive text.

The solution proposed is as follows:

[+] Spoiler

Buttons with an icon - A title followed by colons and paragraph break. Descriptive text on second paragraph. If no description is necessary, the tooltip will only contain the button title, with no colons.


Buttons with text - Tooltip only contains descriptive text, since the title is already written on the button.

Overall writing

Using short and simple sentences, avoiding repetitions, and clarifying functions and keyboard commands with precision. An example below:

[+] Spoiler

Original text
:{BLACK}Build railway signals. Ctrl toggles semaphore/light signals{}Dragging builds signals along a straight stretch of rail. Ctrl builds signals up to the next junction or signal{}Ctrl+Click toggles opening the signal selection window. Shift toggles building/showing cost estimate

Modified text
:{BLACK}Build railway signals:{}Ctrl+Click switches between semaphore/electric variants when a signal type is selected. Click+Drag builds signals along a straight stretch of rail. Ctrl+Click+Drag builds signals up to the next junction or existing signal. Ctrl+Click on an existing signal converts between signal types at no cost. Shift+Click shows estimated cost without purchase

My main source of inspiration for incoming changes is the Microsoft style guide. So feel free to check it out and let me know your opinion!

[kamnet]

So far, so good!

[mcbanhas]

Here's a preview on how some of the rule changes will affect the text. Be aware that for convenience's sake I'm comparing unaltered EN-US to modified EN-UK, so there will be some wording differences on the screenshots. Kindly ignore those.

Starting with capitalization. By applying sentence style on buttons the menu becomes lighter and a bit easier to read. Note that "Scenario Editor" still maintains Title Capitalization because it is the name of a program within the game (although I might change this, since the official full name is "OpenTTD Scenario Editor", and the button might only refer to the function itself).

Original version up, modified version down




More capitalization changes. By making all field text follow sentence capitalization, you can notice it becomes less dense.

Original version up, modified version down




Formatting and rewriting changes on tooltips. Here you can see the changes added by separating title from description, and rewriting the shortcuts text to be more concise.

Original version up, modified version down

[perverted monkey]

I propose a simpler menu for first 4 buttons:
New, Load, Scenario, Heightmap.

Let me object to changing Quit to Exit. I, and I suppose other gamers too, expect exit to close the console of a game and quit to quit the game.

You are doing a great job with Tooltips.

[andythenorth]

Quit is Quit, at least on macOS where it's part of the UI style requirements.

If we really have to change commands and buttons to sentence case, please change 'Scenario Editor' to 'Scenario Editor'. It's irrelevant whether that one is a proper noun, it will cause bug reports.

Sorry if this reads as grumpy, I have spent too much life arguing sentence case versus title case in UI buttons, I was hoping to never see it again

The general change to sentence case (e.g. finances table) looks better, more readable and more space efficient.

[mcbanhas]

Quit is Quit, at least on macOS where it's part of the UI style requirements.

Quit is EN-US. I mentioned in the first post that I'm using EN-US on the screenshots as an unmodified original because it's easier than changing the lng file every time. So the final version will be "Exit" as it was before.

If we really have to change commands and buttons to sentence case, please change 'Scenario Editor' to 'Scenario Editor'. It's irrelevant whether that one is a proper noun, it will cause bug reports.

Sorry if this reads as grumpy, I have spent too much life arguing sentence case versus title case in UI buttons, I was hoping to never see it again

The general change to sentence case (e.g. finances table) looks better, more readable and more space efficient.

No problem, I'll keep it all lowercase, because like I said, there's a good argument for it. I've been through it myself (I originally favored Title Capitalization for buttons too), but ultimately I got to see that Sentence capitalization works much much better for complex, information heavy UIs like OpenTTD's. Here's an example on how Title Capitalization can easily make a simple command seem awkward:



This is the EN-US original, but EN-UK is pretty much the same. Do notice how the buttons text is inconsistent by default (the train order buttons being in ST while the "Go To" button is in TT)

[Hyronymus]

This is the EN-US original, but EN-UK is pretty much the same. Do notice how the buttons text is inconsistent by default (the train order buttons being in ST while the "Go To" button is in TT)

If ST / TT means centered or not centered then the reason might be having a drop down button or not: Go To has a drop down button and Skip and Delete have not.

[mcbanhas]

If ST / TT means centered or not centered then the reason might be having a drop down button or not: Go To has a drop down button and Skip and Delete have not.

It means Sentence capitalization and Title Capitalization. Yes, you are right that those are indeed drop down window buttons, but it's still an inconsistent use, as far as I am aware.

*EDIT* As a matter of fact, the Go To button actually has a drop down menu of its own, and is inconsistent with the rest of the items.

[mcbanhas]

Sometimes you get a sense of how much of a dumpster fire the OpenTTD UI can sometimes be just by looking at the tooltips. Here's the original and edited versions of the Go to tool. Not even streamlining text and removing not-so-important stuff entirely fixes it.

[mcbanhas]

https://wiki.openttd.org/Manual_of_style

The first version of the manual is now complete!

Will soon begin the creation of a final version of the improved UI texts!

[2TallTyler]

I never realized I'm the type of person to read a manual of style end-to-end for fun, but here we are. This is the sort of work which is so rarely noticed or appreciated, but makes such a huge difference for usability and a feeling of quality. Keep up the great work.

[mcbanhas]

Hello, thank you very much for your kind words. I'm only trying to add a little contribution to the project based on my actual skills.

[MagicBuzz]

Hello,

I discover this topic.

I have a small suggestion : on tooltips for icon buttons, are the two points following the title are usefull?
May the title should be bolder though.

[Eddi]

we don't have enough fonts to make something "bold", and deep architectural changes like that are out of scope for a "style guide"

[MagicBuzz]

Yes, I understand.
But what about the double points?

[jfs]

What do you mean by "double points"? Full stop/period? Colon?
There aren't any doubled periods anywhere (that would be wrong regardless), nor any colons.

[SciFurz]

Something that I just remembered, when (re-)writing the tooltips, add the hotkey for the button to the text?
Right now there's no easy way to determine which key or combination it is.

[MagicBuzz]

What do you mean by "double points"? Full stop/period? Colon?
There aren't any doubled periods anywhere (that would be wrong regardless), nor any colons.

Sorry, I mean "colon" (in french that's simply called "deux point" ie "two points"... I did know the "semi-colon" but not "colon" all alone, I thought it was just something just after "anus" )

In the first post there is this screenshot :

Buttons with an icon - A title followed by colons and paragraph break. Descriptive text on second paragraph. If no description is necessary, the tooltip will only contain the button title, with no colons.


IMO, this should be nicer with :

Company ships
Ctrl+Click opens vehicle list only

Without the colon.

[2TallTyler]

Something that I just remembered, when (re-)writing the tooltips, add the hotkey for the button to the text?
Right now there's no easy way to determine which key or combination it is.

I second this suggestion. When I'm learning a game, tooltips are the first place I look for hotkeys, followed by the controls menu (not present in OpenTTD). As far as I know, the only place hotkeys are listed is on the Wiki.

[Eddi]

Something that I just remembered, when (re-)writing the tooltips, add the hotkey for the button to the text?
Right now there's no easy way to determine which key or combination it is.

since hotkeys are configurable, this would require a placeholder command like "{HOTKEY}" (which i don't think exists yet)