A manual of style for OpenTTD
Moderator: OpenTTD Developers
A manual of style for OpenTTD
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:
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:
Overall writing
Using short and simple sentences, avoiding repetitions, and clarifying functions and keyboard commands with precision. An example below:
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!
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:
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:
Overall writing
Using short and simple sentences, avoiding repetitions, and clarifying functions and keyboard commands with precision. An example below:
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!
Re: A manual of style for OpenTTD
So far, so good!
Do you like drones, quadcopters & flying toys? Check out Drone Strike Force!
Base Music Sets: OpenMSX | Scott Joplin Anthology | Traditional Winter Holiday Music | Modern Motion Music
Other Projects: 2CC Trams | Modern Waypoints | Sprite Sandbox & NewGRF Releases | Ideabox | Town Names | Isle of Sodor Scenario | Random Sprite Repository
Misc Topics: My Screenshots | Forgotten NewGRFs | Unfinished Graphics Sets | Stats Shack | GarryG's Auz Sets
Base Music Sets: OpenMSX | Scott Joplin Anthology | Traditional Winter Holiday Music | Modern Motion Music
Other Projects: 2CC Trams | Modern Waypoints | Sprite Sandbox & NewGRF Releases | Ideabox | Town Names | Isle of Sodor Scenario | Random Sprite Repository
Misc Topics: My Screenshots | Forgotten NewGRFs | Unfinished Graphics Sets | Stats Shack | GarryG's Auz Sets
Re: A manual of style for OpenTTD
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
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
-
- Traffic Manager
- Posts: 161
- Joined: 02 Mar 2009 02:07
Re: A manual of style for OpenTTD
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.
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
- Tycoon
- Posts: 5658
- Joined: 31 Mar 2007 14:23
- Location: Lost in Music
Re: A manual of style for OpenTTD
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.
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.
FIRS Industry Replacement Set (released) | HEQS Heavy Equipment Set (trucks, industrial trams and more) (finished)
Unsinkable Sam (ships) (preview released) | CHIPS Has Improved Players' Stations (finished)
Iron Horse ((trains) (released) | Termite (tracks for Iron Horse) (released) | Busy Bee (game script) (released)
Road Hog (road vehicles and trams) (released)
Unsinkable Sam (ships) (preview released) | CHIPS Has Improved Players' Stations (finished)
Iron Horse ((trains) (released) | Termite (tracks for Iron Horse) (released) | Busy Bee (game script) (released)
Road Hog (road vehicles and trams) (released)
Re: A manual of style for OpenTTD
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 Quit is Quit, at least on macOS where it's part of the UI style requirements.
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:andythenorth wrote: ↑11 Apr 2020 06:19If 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.
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)
Re: A manual of style for OpenTTD
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.
Re: A manual of style for OpenTTD
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.
Re: A manual of style for OpenTTD
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.
Re: A manual of style for OpenTTD
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!
The first version of the manual is now complete!
Will soon begin the creation of a final version of the improved UI texts!
- 2TallTyler
- Route Supervisor
- Posts: 507
- Joined: 11 Aug 2019 18:15
- Contact:
Re: A manual of style for OpenTTD
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.
Re: A manual of style for OpenTTD
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.
Re: A manual of style for OpenTTD
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.
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.
Re: A manual of style for OpenTTD
we don't have enough fonts to make something "bold", and deep architectural changes like that are out of scope for a "style guide"
Re: A manual of style for OpenTTD
Yes, I understand.
But what about the double points?
But what about the double points?
Re: A manual of style for OpenTTD
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.
There aren't any doubled periods anywhere (that would be wrong regardless), nor any colons.
Tooltip option?
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.
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/
See http://scifurz.wordpress.com/
Re: A manual of style for OpenTTD
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" )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.
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 :
Without the colon.Company ships
Ctrl+Click opens vehicle list only
- 2TallTyler
- Route Supervisor
- Posts: 507
- Joined: 11 Aug 2019 18:15
- Contact:
Re: Tooltip option?
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.
Re: Tooltip option?
since hotkeys are configurable, this would require a placeholder command like "{HOTKEY}" (which i don't think exists yet)
Who is online
Users browsing this forum: No registered users and 49 guests