A manual of style for OpenTTD
Posted: 09 Apr 2020 20:53
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!
