Update translations/coordinating.rst
#1587
Conversation
| This will allow you to plug your translation into docsbuild-scripts_, and it | ||
| will be found at ``docs.python.org/LANG/``, but not in the switcher. | ||
|
|
||
| This will be done XXX | ||
|
|
||
| .. XXX When ...? Discussion needed... | ||
| .. My idea: Time based, e.g. 2 months of activity, showing that they aren't going anywhere |
There was a problem hiding this comment.
EB It would be nice to note something here.
|
While this has to wait for a pending issue, other discussion should continue. These are comments I left in the file in the format, Requesting @rffontenelle and @m-aciek |
| .. XXX https://github.com/python/devguide/issues/1586 | ||
|
|
||
| Once the following resources have been fully translated on the XXX branch: |
There was a problem hiding this comment.
I guess these XXX requires closing that issue before merging this? Alternatively, you could use a text that doesn't mention which branch, and leave the branch requirement for another PR.
| While initially one person is fine, we recommend expanding to having two or | ||
| three coordinators. You can find more on choosing coordinators in the FAQ below. | ||
|
|
||
| .. XXX move stuff from the FAQ? |
There was a problem hiding this comment.
XXX to be solved before merging
There was a problem hiding this comment.
Yes that is the goal
If we cannot find a resolution in reasonable time, I'll fallback to neutral wording and we'll do it in a follow up.
|
Thanks for the review. I should have my editor highlight it in red:-) |
| .. figure:: translator-workload.svg | ||
| :class: invert-in-dark-mode | ||
| :align: center | ||
| :alt: An exaggerated chart showing that individual translator workload | ||
| decreases with the amount of translators. | ||
|
|
There was a problem hiding this comment.
I'm not sure we need an image to explain the concept of "translating is easier if there are more people to do it" (and after a certain point it might get more difficult again if there are too many translators to coordinate).
There was a problem hiding this comment.
I added it for emphasis, but if the general consensus is against it I am happy to remove it.
There was a problem hiding this comment.
I think I personally like the figure, a bit of exaggeration here may be suggestive, to motivate to form a team. I think I remember Julien writing on some mailing list, that for one person translating whole documentation is a work for 40 years, or similar?
I would add arrows on the axes, to express the direction of growth, as there's no scale.
And change Translators to Number of translators?
There was a problem hiding this comment.
Per this article, a professional translator can do 400-600 words per hour, so let's assume we can do 400 w/h. Let's also assume you can dedicate an hour each day (every day) to translating. The total translatable word-count is currently 1,606,150. That means it would take ~4015 days to translate, which is actually exactly 11 years. (And so, realistically it would take ∞ because most people would get demotivated after the third year of monotonous translation...) But, this estimate does not take into account the fact that your translations are constantly being invalidated.
I like the arrows idea:-)
| The branch name should be the version, for example, ``3.14``, and the files | ||
| should be structured like the source files in `CPython/Doc <https://github.com/python/cpython/tree/main/Doc>`_. | ||
| A correctly set up repository looks like this: `python-docs-pl <https://github.com/python/python-docs-pl/>`_ |
There was a problem hiding this comment.
The first sentence is not very clear. Should there be only one branch? Should it match the latest released version, or the in-development version? Should it replace main or be created in addition to main? Can there be multiple branches?
In addition, I think it might be worth specifying the name of the repo as well (python-docs-xx, where xx is the language code.
There was a problem hiding this comment.
Should there be only one branch?
I will try to find a better wording, though this is for a new translation, so they will most likely start with one anyway.
Should it match the latest released version, or the in-development version?
That is an ongoing discussion in the linked issue, and is currently covered in the FAQ.
Should it replace main or be created in addition to main?
I don't think there is a need to cover that, whether they want to keep it or not is up to them, only the location for the actual translation files is required for it to be built.
| .. figure:: translator-workload.svg | ||
| :class: invert-in-dark-mode | ||
| :align: center | ||
| :alt: An exaggerated chart showing that individual translator workload | ||
| decreases with the amount of translators. | ||
|
|
There was a problem hiding this comment.
I think I personally like the figure, a bit of exaggeration here may be suggestive, to motivate to form a team. I think I remember Julien writing on some mailing list, that for one person translating whole documentation is a work for 40 years, or similar?
I would add arrows on the axes, to express the direction of growth, as there's no scale.
And change Translators to Number of translators?
This page is aimed at coordinators, so I assume some git/gh knowledge etc.
Some things that need to be discussed:
closes #1586
📚 Documentation preview 📚: https://cpython-devguide--1587.org.readthedocs.build/