Better progress.md

[Duke-M-commits]

As of now the table in progress.md has some downsides:

• Table is cut off because of long contents per cell (the git webview is probably the most seen visual representation for that file)
• Percentages with 3 decimal places are a bit too detailed to be nice to read (the file is meant to be read by humans, it wont get reread by a machine)
• Fully translated languages are included in the table which rises the width further (but there isn't a breakdown information in these to be found by the reading person)

I sketched a shorter and easier to read document:

• shortened the language-columns (first 3 characters of language string) and added tooltips with full names on hover
• removed percentages in the whole (that's something for a nice comparison graph)
• removed fully translated language columns
• added a list of fully translated languages at the top
• removed non curated language columns
• added a list of non curated languages at the bottom
• linked files to their directories

I created a mockup here
How about that?
And why? I think a good representation of the progress could motivate new visitors to contribute.

Disclaimer: I can't write GO, so I can only provide my input, somebody else would have to change update_translations.go

Before:

After:

Originally posted by @DukeDukeEm in #512

[zhongqingsong]

This new style is great. But if there are more countries and regions, there will still be more than the boundaries of the page display. When that happens, it's even more troublesome. So, I adjusted the presentation of the whole data. It went from horizontal to vertical.
Like below (Data and language are arbitrary and do not represent progress results. It's only used for styling.):

In this way, there is no need to worry about new situations arising as more countries and regions grow. Of course, we need to trim some of the names of the files.

[BenLubar]

Does the grid actually help with readability, or would it be better to have one section per language with a summary of what's incomplete? If we do that, we can also add stuff like mail and link directly to files that need updating.

[zhongqingsong]

Does the grid actually help with readability, or would it be better to have one section per language with a summary of what's incomplete? If we do that, we can also add stuff like mail and link directly to files that need updating.

I think Yes, first of all, the new md, whether it's Duke or my style, It looks neat, and you can see the data for each language at a glance. Second, it is very convenient to view the data. The old way of presenting data, especially in the last countries. They had to click on the scroll bar with their mouse and drag it manually. You have to reclick the scroll bar if you make a mistake. With the new data presentation, people just need to scroll the mouse wheel to see all the data, it's much easier!!

[Blueberryy]

What about icons for languages and file names?

[Duke-M-commits]

What about icons for languages and file names?

There are no icons for languages, there are only flag-icons for countries, using flags for languages is troublesome.
As an example, I translate into german, this language is officially spoken in 3 countries, which ends in something like this:

Another example could be the differentiation between schinese and tchinese.

Icons for files: I don't understand how this could not be just an repeated file icon. Please explain :)

[Blueberryy]

What about icons for languages and file names?

There are no icons for languages, there are only flag-icons for countries, using flags for languages is troublesome. As an example, I translate into german, this language is officially spoken in 3 countries, which ends in something like this: Another example could be the differentiation between schinese and tchinese.

Icons for files: I don't understand how this could not be just an repeated file icon. Please explain :)

ah gotcha, well then i think it's all good to open pull request with your improvements

[Duke-M-commits]

No, my mockup is static, it can't update on it's own like the current md.

[Duke-M-commits]

Does the grid actually help with readability, or would it be better to have one section per language with a summary of what's incomplete? If we do that, we can also add stuff like mail and link directly to files that need updating.

I do think we should see something which allows to compare all languages in one place. Having a section per language sounds like it would make the progress report much longer. And such it would defeat the purpose of motivating new users to contribute. So yes, it helps the readability by a lot ... for the right targetgroup. A longer report per language would be helpful for already contributing users, I do not think this should be the targetgroup, they can just search for double tabs in the beginning of the line and get what they need in the course of translating.

I believe the end result should be short and well structured. I shouldn't end in any deep analysis.

[Duke-M-commits]

This new style is great. But if there are more countries and regions, there will still be more than the boundaries of the page display. When that happens, it's even more troublesome. So, I adjusted the presentation of the whole data. It went from horizontal to vertical. Like below (Data and language are arbitrary and do not represent progress results. It's only used for styling.):

In this way, there is no need to worry about new situations arising as more countries and regions grow. Of course, we need to trim some of the names of the files.

The list of different files/folders will certainly rise, the list of languages won't jump up so fast, we can think (eg. shorten the file-column somehow) about changing the layout with switched axis when the problem starts to really exist.

[zhongqingsong]

Yes, there won't be many languages in a short time. But it's important to note that when you really need to switch between horizontal and vertical axes, it's not easy. The md is not Excel, it can not automatically convert horizontal and vertical axes, it needs to rewrite the code to adjust.

[Duke-M-commits]

Yes you can, as far as i know that's a mapped array out of which an markdown table is generated. Since I can't do that, I need to be careful how I promote the easieness of such a change, but it's certainly better to handle than an Excel sheet.

[BenLubar]

Right now, the markdown output (search https://github.com/ReactiveDrop/reactivedrop_translations/blob/e490cd130ad0af425fd43f51ef760daf5186e904/utils/update_translations.go for flagMarkdown) is just fancy log messages. Given how we've ended up using the sync tool with the CI bot, it's probably best to separate the progress.md generation from the actual sync process so it's less tightly coupled and we can do whatever formatting of the information makes the most sense.

[BenLubar]

I've updated PROGRESS.md - how does it look?

[Duke-M-commits]

It's now more technically helpful for already working translators.
It lost all and any incentive for new visitors to do or see anything motivating which they could work on.
So you made it even more helpful and wholesome as it was ... into the opposite direction I proposed.

• the user has to scroll for long
• the user has to click very much
• the user has no comparison to what is done or missing

It deserves a new name, maybe 'progression helper'.

My proposed view - which I see now, I have never directly stated - has the following targets:
A fresh visitor/possible future translator should

• see what is done already (the mass of green checkmarks looks great, and the work which has been done already IS great)
• should be given the impression that it isn't a complicated or long work (which it isn't for the first 80%, the devil lies in the detail, but that's nothing which should be called out first)
• shouldn't need to scroll or click (just a short invitation to top something up to 100%, to achieve a little green checkmark, like hunting a badge)

Less is more, especially for beginners, and we need more beginners, the people which already work on the translation are doing a great job, and they are helping each other, bit by bit. This structure isn't complex enough to require a tool which tells you what is missing, I mean yea, It's a nice to have for sure, but it's not what is needed to get more people into the boat.

As a feedback for what it is now:
I like it very much, it's useful.

As a feedback for how it could be improved even more:
The expand/collapse feature should be used once per language, so an eg. italian translator scrolls to his language, clicks once, gets a detailed list for all he needs to do next.

PS:
My personal incentive was ... I know this sounds silly ... but I believe it works (so it can't be that stupid) ... plain and simple ... bragging rights or also glaring on your checkmark as it's your 100% Steam achievement list.

PPS:
I didn't make this whole wiki thing for me, all of it is build with the same idea: creating a smooth slide for new players and contributors to step in. That's also something I don't think I ever stated. Most of my painstakingly small but broad changes are to ensure new contributors aren't deterred by chaos or cumbersome self-research and testing.

[BenLubar]

I've added a summary table to the top. How does that look?

[Duke-M-commits]

Wow, very good. Now it has everything at once, a well arranged first-glance comparison, all the details and the proposed axis.
I don't get the difference between the capitalized and non-capitalized column-headers. What does "Strings" include?

[BenLubar]

Non-capitalized headers are specific strings files, the Strings header is strings not included in one of the files that gets an individual header.

Inventory is the number of missing language-specific keys in the inventory schema, and Files is the number of files that are missing or contain indented lines.

[Duke-M-commits]

I am very very happy with the outcome of this issue. The progress report is now really helpful for everyone, thanks to everyone involved.