A manual of style for OpenTTD

Forum for technical discussions regarding development. If you have a general suggestion, problem or comment, please use one of the other forums.

Moderator: OpenTTD Developers

mcbanhas
Engineer
Engineer
Posts: 12
Joined: 13 Dec 2019 14:39

A manual of style for OpenTTD

Post by 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.
Image

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

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!


mcbanhas
Engineer
Engineer
Posts: 12
Joined: 13 Dec 2019 14:39

Re: A manual of style for OpenTTD

Post by 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

Image


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

Original version up, modified version down

Image


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

Image

perverted monkey
Engineer
Engineer
Posts: 61
Joined: 02 Mar 2009 02:07

Re: A manual of style for OpenTTD

Post by 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. :D

User avatar
andythenorth
Tycoon
Tycoon
Posts: 5216
Joined: 31 Mar 2007 14:23
Location: Lost in Music

Re: A manual of style for OpenTTD

Post by 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 :shock:

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

mcbanhas
Engineer
Engineer
Posts: 12
Joined: 13 Dec 2019 14:39

Re: A manual of style for OpenTTD

Post by mcbanhas »

andythenorth wrote:
11 Apr 2020 06:19
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.
andythenorth wrote:
11 Apr 2020 06:19
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 :shock:

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:

Image

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)

User avatar
Hyronymus
Tycoon
Tycoon
Posts: 13221
Joined: 03 Dec 2002 10:36
Location: The Netherlands
Contact:

Re: A manual of style for OpenTTD

Post by Hyronymus »

mcbanhas wrote:
11 Apr 2020 09:18
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
Engineer
Engineer
Posts: 12
Joined: 13 Dec 2019 14:39

Re: A manual of style for OpenTTD

Post by mcbanhas »

Hyronymus wrote:
11 Apr 2020 12:22
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.

Image

mcbanhas
Engineer
Engineer
Posts: 12
Joined: 13 Dec 2019 14:39

Re: A manual of style for OpenTTD

Post by 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.

Image

mcbanhas
Engineer
Engineer
Posts: 12
Joined: 13 Dec 2019 14:39

Re: A manual of style for OpenTTD

Post by 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!

User avatar
2TallTyler
Traffic Manager
Traffic Manager
Posts: 165
Joined: 11 Aug 2019 18:15
Contact:

Re: A manual of style for OpenTTD

Post by 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
Engineer
Engineer
Posts: 12
Joined: 13 Dec 2019 14:39

Re: A manual of style for OpenTTD

Post by 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.

User avatar
MagicBuzz
Tycoon
Tycoon
Posts: 1264
Joined: 15 Feb 2003 17:32
Location: Villefranche-sur-Saône, France

Re: A manual of style for OpenTTD

Post by 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
Tycoon
Tycoon
Posts: 7479
Joined: 17 Jan 2007 00:14

Re: A manual of style for OpenTTD

Post by 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"
You might not exactly be interested in Ferion, but if you are, have fun :)

User avatar
MagicBuzz
Tycoon
Tycoon
Posts: 1264
Joined: 15 Feb 2003 17:32
Location: Villefranche-sur-Saône, France

Re: A manual of style for OpenTTD

Post by MagicBuzz »

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

User avatar
jfs
Tycoon
Tycoon
Posts: 1240
Joined: 08 Jan 2003 23:09
Location: Denmark

Re: A manual of style for OpenTTD

Post by 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.

User avatar
SciFurz
Engineer
Engineer
Posts: 116
Joined: 13 Oct 2018 16:33
Contact:

Tooltip option?

Post by 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.
Tinkering in the code in between writing mostly naughty stuff.
See http://scifurz.wordpress.com/

User avatar
MagicBuzz
Tycoon
Tycoon
Posts: 1264
Joined: 15 Feb 2003 17:32
Location: Villefranche-sur-Saône, France

Re: A manual of style for OpenTTD

Post by MagicBuzz »

jfs wrote:
09 Jul 2020 11:28
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" :D )

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.
Image

IMO, this should be nicer with :
Company ships
Ctrl+Click opens vehicle list only
Without the colon.

User avatar
2TallTyler
Traffic Manager
Traffic Manager
Posts: 165
Joined: 11 Aug 2019 18:15
Contact:

Re: Tooltip option?

Post by 2TallTyler »

SciFurz wrote:
10 Jul 2020 08:52
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
Tycoon
Tycoon
Posts: 7479
Joined: 17 Jan 2007 00:14

Re: Tooltip option?

Post by Eddi »

SciFurz wrote:
10 Jul 2020 08:52
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)
You might not exactly be interested in Ferion, but if you are, have fun :)

Post Reply

Return to “OpenTTD Development”

Who is online

Users browsing this forum: No registered users and 3 guests