Core developer and Python Docs Editorial Board member Mariatta presented an update on the Python Docs Editorial Board to the Language Summit. Mariatta credited her fellow board members Carol Willing, Guido van Rossum, Joanna Jablonski, and Ned Batchelder for putting together the presentation.
Mariatta started with the mission and vision of the Python Docs Editorial Board, including improving the quality of the Python documentation, getting consensus, and being the final decision makers for documentation issues. Mariatta pointed to the editorial board’s website, which hosts meeting minutes and a “changelog” of decisions.
Mariatta highlighted a few recent decisions, including using the vertical bar (“|”) instead of “or” when describing type information in function parameters and the use of “timezone” versus “time zone” in prose. Ned Batchelder is working on the developer guide, which will “eventually become the new contributors guide for Python”. The group is also modernizing Python tutorials, and Joanna Jablonski and Savannah Bailey are auditing the argparse module documentation.
Mariatta shared that the vision of the Docs Editorial Board is to change Python documentation into a community resource. They hope to do this by making decisions to encourage new contributors and by reducing instances of an individual claiming ownership of a document. The board shared they are “seeing improvement” on this front.
Mariatta celebrated that the board was seeing more collaboration among different groups, such as a renewed emphasis on translations and usability of the documentation. Folks from the Python Software Foundation Education and Outreach Working Group have come to the documentation Discord asking questions and offering help.
Discussion
A short, rapid-fire discussion broke out amongst core developers about the sometimes unfortunate state of pages on the “python.org” subdomain, such as a multitude of wikis. Thomas Wouters and Ned Deily remarked on the previous website revamp and how to avoid breakages, it was “easier to keep pages around, but that doesn’t mean anyone is responsible for the pages”.
Carol Willing, speaking for herself, thought it was “overdue to get rid of links to the wiki, particularly ones that have beginner Python stuff”. PSF executive director Deb Nicholson added that the PSF board was taking a “super macro view of python.org” and to “get in touch with the User Success Working Group if people have questions”.
Python documentation translations were a big topic of conversation during this Language Summit session. Mariatta noted that there were a few language translation groups that were “successful”, giving Korean and Spanish Python docs translations as examples. “We want to learn from groups like that so that even more languages can have that experience”, Mariatta shared, noting that PEP 545, which documents the Python documentation translation guide, focused too heavily on “getting started” rather than “how to continue”.
One of the highlighted issues of PEP 545 was that there would be a single coordinator and no process for adding additional translation coordinators in the case that existing coordinators weren’t available. Mariatta asked the group whether a new governance process, subcommittee, or working group might be able to step in in these situations to “unblock a translation community”.
Lysandros Nikolaou, who has been involved in the Greek translation of the Python docs, highlighted that knowledge-sharing across different translation groups is difficult and a significant barrier to other translations being successful, especially those with smaller communities. “PEP 545 specifies that translations have to have content in the translation language related to the CLA and license,” and this requirement “makes it very difficult for different communities to interact with each other and share knowledge”.
Lysandros shared how the Greek translation group started by “going to the Spanish translation repository and then translating [their processes] from Spanish to English to know what to do”. Lysandros argued that having only one translation coordinator shouldn’t be allowed, and that it’s “difficult enough working on a translation project let alone just one person working on [the translation project]” and that many teams that work on translations know “very little about how to do [process] documentation”. Lysandros agreed that bringing together coordinators would be helpful to every translation.
Donghee Na suggested standardizing on the translation platform across translation groups so that each group can focus their energy on the translation instead of “focusing energy on redoing the same work over and over”.