Mailman 3 May 2018 - Doc-SIG

Brazilian Portuguese translation coordinate
by Marco Rougeth Aug. 2, 2018

Aug. 2, 2018

Hi, I'm Marco Rougeth <https://rgth.co>, member of the Brazilian Python community. I'm volunteering to coordinate the pt_BR translation of the Python documentation. We already have some strings translated on Transifex and we just merge efforts with our local Django community to speed up the translations. We're talking at a Telegram group (@pythonbr_i18n <https://telegram.me/joinchat/CjIqFj4UVvCtPnCwxUDJLA>). Bests, Marco.

5 11

Coordinating zh_TW (Taiwanese Mandarin) Translations
by Adrian Liaw June 25, 2018

June 25, 2018

Hi all, This is Adrian from Taiwan, I'm currently a core organising staff at PyCon TW, and I would like to volunteer as the coordinator of zh_TW (Taiwanese Mandarin) translations! The current translations (although it's not complete enough to add it to the language switcher) are hosted on our own GitHub repository ( https://github.com/python-doc-tw/cpython-tw/tree/tw-3.6/Doc/locale/zh_TW/LC…) and on our own Transifex project ( https://www.transifex.com/python-tw-doc/python-36-tw), and I would like to migrate them into the PEP 545 workflow. However, I have a concern here, if I migrate the translations to the official Transifex project for Python documentation translations, that way it may completely lost the metadata of each string including history and translator, which I think is probably a bad thing to happen. I'm wondering if anyone knows whether there's some way to solve this problem or it's currently an unsupported feature (migrating translation metadata along with the translations) on Transifex? Thank you for taking time reading this, thank you for your contributions, and I'm super excited about making more contributions to the Python community! Best Regards, Wey-Han "Adrian" Liaw -- Wey-Han "Adrian" Liaw (@adrianliaw) http://linkedin.com/in/adrianliaw

4 10

readability of sample programs in tutorial
by Xuan Wu May 14, 2018

May 14, 2018

Hi, when reading some of the sample codes in the official tutorial, I had to do research to understand the background of naming and string constants, like those strings from the script of Monty Python. Still this one in $5.5 is the most challenging so far: >>>tel = {'jack': 4098, 'sape': 4139} >>>tel['guido'] = 4127 >>>tel {'sape': 4139, 'guido': 4127, 'jack': 4098} >>>tel['jack'] 4098 ... I did quite some digging to confirm my guess of the hidden meaning, during which I realized it was initially written 27 years ago, without much change so far. Now I'm curious if its meaning is obvious to most nowadays beginners even as English speakers. In general, I wonder if there was discussion of revising some sample programs for better readability or adding more comments/introductory texts? Thanks.

3 4

Video content in the standard library documentation
by anthony shaw May 7, 2018

May 7, 2018

Hi I spend a lot of time reading the standard library documentation pages and then condensing them down into small videos as part of either commercial instructional courses or internal training. The problem is that all this work is isn’t much help to the PSF or the wider community. It’s my view that many people can sit and read the reference pages when they really need to check function or class documentation but beginners can find the pages stifling, with lots of new words, phrases and references to other stdlib modules. I was thinking of providing a set of templates and guidelines for having “5 minute overview” videos at the top of each standard library page. Videos would be embedded in the existing docs, starting with 3.7. Videos would first explain - why this module exists? What problem is it solving - core concepts and ideas - most basic usage examples with demos - where to find more information and other related modules Because modules change between minor versions, videos should not be a comprehensive guide to the module, but a starter guide for people unfamiliar with the module. The template, standards and guidelines for the creation of these video clips would live in the PSF documentation domain, as well as the review checklist and guidelines for adding them. Because many people would end up authoring the videos, consistency would be important, so a structured format and template is critical. I’m happy to volunteer to help create the template and guidelines. I know lots of teachers in the Python world who (hopefully) could start to contribute videos as well. Regards Anthony Shaw

4 5

Re: [Doc-SIG] Translating sample programs in documentation
by Shengjing Zhu May 4, 2018

May 4, 2018

Sorry I just joined this list, maybe I lost the mail thread index. Since I have private email with Xuan about d.p.o Chinese translation, and he mentions translating code blocks and this thread on doc-sig, I'd like to reply publicly on list. > My point of view is we should not translate them, as we dont want to see ` ``for 词 in 词表:` pushed by anyone (I mean : we're writing code in english, even if the doc is translated we *still* have to write the code in english). Also, we have enough work translating the text, we don't need more. +1 I'd be strongly against translating variable names(identifier) to any language other than English. We write code in English, we share code around world. To write code in Chinese doesn't make any sense, only prevent other people reading the code. BTW, I joined the transifex Chinese team, and started to translate, let's make it meet the pep545 requirement first. And setup a temporary site to preview the result, https://zhsj.github.io/python-docs-zh-cn/ -- Regards, Shengjing Zhu

1 0