[{"content":"Notes Updates from the Education \u0026amp; Outreach WG We learned about what their current goals are, and who the current members are. Their goals are: Update python.org education and resource list, create a webpage instead of the wiki, build an official beginner tutorial, and to flesh out community and conference organizers\u0026rsquo; toolkit. Overlap with our scope: tutorials. What are the action items with the Education \u0026amp; Outreach WG? There was talk at the core sprint about adding a more interactive tutorial. Where do we want it to live, and what do we want to do? We can offer help and support and leave it up to them Encourage them in this effort We’d love to see more education resources to not be directed to the wiki. E.g. the PSF website shouldn’t direct people to wiki about educational resources. Can there be a group/person who can commit to maintaining the PSF wiki pages? Many aspects of the wiki are outdated. The current Wiki’s accessibility is outdated Could there be a different “wiki”-like platform? Who/Where can we pass these opinions to, since these are out of our scope? History of PSF wiki: Moinmoin is the first wiki platform in Python. Original dev is no longer actively participating. https://www.python.org/psf/workgroups/#education-outreach-work-group Many pages in the wiki are now unmaintained Some of the outdated wiki may still have important information It would be great to go through the content, move information elsewhere, etc. Who has permission to give edit access? Marc Andre. Let’s continue to stay in touch with the Edu \u0026amp; Outreach WG. Maybe we can share our opinion with them about the wiki. The wiki is not our scope. What is our scope: Some pages in the wiki should be in the official Python doc. We can request to move content to Python doc, and ask them to delete from Wiki https://wiki.python.org/moin/TimeComplexity Similarly: how to document free-threading? Carol worked on an outline with others It will be an issue in the public Quansight free-threaded repo Aimed for the 3.15 time-frame Possible topics to cover: What does Python guarantee How to write safe software How to write performant software Difficult because it changes over time Will involve third-party libraries Translations The Transifex glossary was erased by a malicious translator (https://discuss.python.org/t/104357) But it can be retrieved Are other tools better for public groups with unknown levels of trust? Offline update from Stan: The glossary issue could have been prevented by modifying the settings. Stan is conducting an audit to see if there are any other such gaps. However, this still leaves the major risk of the fact that malicious translations could be quite easily injected into the official docs. This is quite a complicated topic, and not so much related to the tool. ","permalink":"https://python.github.io/editorial-board/updates/2025-10-14/","summary":"Meeting Minutes from Python Docs Editorial Board: Oct 14, 2025","title":"Meeting Minutes: Oct 14, 2025"},{"content":"Notes We’re a bit disorganized in tracking action items We\u0026rsquo;ll go through the action items and todos from the last meeting TODO: find out where they are coordinating online (mariatta) Who are the Edu \u0026amp; Outreach? Kattni, Keith the ee, Nicholas Tollervey, Jeff Jacobson, Sheena What is the purpose? To learn what they’re doing, what we’re doing, what’s the overlap. TODO: find out from the translators what happens when the source docs change Are we still needed here? There is inconsistency with the different translations groups. Do they need to be consistent? We now get Transifex funded through the PSF core devs fund. But there are other competing options. Do we want to remain in the business of translations? Can we delegate to another group? Should we be explicit in saying we want a sub WG? What do we want this group to be? To coordinate and to support the translations effort Example: Adam Turner led the work about Transifex What is involved in all of this? Translation teams are often well meaning volunteers, who haven’t thought about the tools they need and the amount of work involved. Being added to python-docs-somelanguage requires some vetting and giving access. There needs to be an institutional owner. People who want to translate may not be the ones who want to be coordinating. We want them to form a WG (not a person). Python SC has a formal process for creating new WG (eg the way we create this Board through a PEP) We can also create our own WG and have the WG report to us. We can ask in the translations if they want to form a group. TODO: Ned will follow up with updates from devguide and ask the translations team (this is done: https://discord.com/channels/935215565872693329/1102686540007747586/1415080055796666378) Ned has PRs to the CPython docs Sorting the glossary: https://discuss.python.org/t/101778/2: sounds like a great idea ","permalink":"https://python.github.io/editorial-board/updates/2025-09-09/","summary":"Meeting Minutes from Python Docs Editorial Board: Sep 9, 2025","title":"Meeting Minutes: Sep 9, 2025"},{"content":"Agenda: Docs audit with Savannah is on hold Education \u0026amp; Outreach working group Docs WG read-out https://github.com/python/cpython/pull/135160 Side note from the PR: Translation churn Monitoring discuss.python.org Notes Education \u0026amp; Outreach Mariatta was at their open space at PyCon\nKattni, Keith the ee, Nicholas Tollervey, Jeff Jacobson, Sheena were there\nPhoto of the open space: https://photos.google.com/share/AF1QipPYYQgHzj32bYsJZk7IHs5acgR-O8cEzJCv67STV6SXxj33PQACa4O5Awn4FZUXeg?pli=1\u0026amp;key=enBoWmo4VFZiMENUM083akFWODNHUXFIY3lpZnZB Tutorial: no one had a clear answer for where newbs should go\nTODO: find out where they are coordinating online\nThere will be overlap with us\nCarol: wishes python.org had a definition education landing page\n“If you are new to programming…” Our Group is chartered with decision about CPython docs\nEdu group is chartered with outreach\nWe should have tutorial, it should be in python.org\nThere is a governance overlap. We have interest in seeing a Python tutorial, but should it be in our scope?\nA tutorial that is targeting beginners, should be more of the focus of the Edu group, not ours\nDocs WG Monthly meeting Carol ran the meeting well. Discussed translations effort. Good progress. There is a doc and process about translations. Process change should be documented on devguide. And also figure out what needs to be changed in the PEPs. Beginner tutorials were discussed during the meeting. Kattni says she will continue organizing the work. Having interactive tutorials will be a minimum for beginner tutorials. PR https://github.com/python/cpython/pull/135160/files “Argument” vs “Parameter” The terms are used informally, so do we need to be precise? Is the effort worth it, since precision users know what the imprecise people mean? If the precision users can’t agree on the term, then leave it alone. Arguing about the right terminology. If we’re not going to agree what difference would it make. See where the community goes? What’s the downside if the change is not made? Start with smaller surface area to change? Perhaps the c-api folder. Focus there first? But for consistency.. It shouldn\u0026rsquo;t update what’s new in older Python versions? Misc.news / (historical artifacts) .py changes should be done separately than .rst changes, same as .c files. To avoid code churn, and to allow doc changes to backport Prefer to keep it as is due to the size of the PR, but would be more open to change if it’s a smaller PR, eg just for a one module. Typing folks might be interested. Consensus: it’s not worth the change compared to the effort discussing it. TODO: Follow up. Joanna will post a response on the PR. Will include in our Decision log. The above could be general guidance when making doc changes. Sometimes you do need to change code and docs at the same time, but this change was meant to be docs changes and shouldn’t have affected other artifacts. Translations churn It’s ok for docs to move faster and change faster compared to code changes, … except for translations. Any small changes to the docs, reverted the translated content back to english because they weren’t translated yet. TODO: find out from the translators what happens when the source docs change What would the translations group prefer to be notified? How can we notify them, when would they like to be notified? Can a GitHub action post an issue to the translation repos? AI could help fix tiny translations changes, maybe? Every language translation is a separate group with diverging processes and desires “Best practices in docs translation” discussion: https://discuss.python.org/t/best-practices-in-docs-translation/94427 We need to learn more about translations and how each groups work. Lysandros plans to host a Greek translations at PyCon Greece. Said it would be great to have best practises ","permalink":"https://python.github.io/editorial-board/updates/2025-06-10-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: June 10, 2025","title":"Meeting Minutes: June 10, 2025"},{"content":"Agenda Docs audit with Savannah is on hold while she deals with other commitments. She has plans to work on it in the next couple months. Language Summit Notes Language Summit: we have 30 minutes slot to engage with the core team. What are we gonna do? Mariatta, Carol, and Guido will be there Our updates: Not much has happened, docs community have been active There have been a few big decisions Decrease in “entitlement/ownership” of specific docs areas Having a named body has calmed down those and set a tone Start with the positives we’ve seen with docs, it’s more collaborative now Compare with when we started years ago “How it works” documentation moved into code Renewed emphasis on translations, usability, Irit’s work with moving some docs from devguide to code, Ned’s devguide refactoring Sqlite3 docs in Diátaxis spirit Docs audit with Joanna and Savannah Posting meeting minutes Seeing engagements with people outside of Core team Separate Docs Discord server works well Looking forward, vision and future We are here to unblock docs decisions Wiki. Is it not a PSF asset? (It is not) Should CPython’s involvement in docs be Reference docs and Devguide docs? To unblock other efforts such as translations of Docs tutorial. Should it be a PSF thing? Why not Core team’s thing? Maybe could free up funding opportunities if it is a PSF thing. Talk about “How PSF can be more involved with Python docs?” Tutorial, onboarding, etc maybe more suited outside core team. Core team docs should just be Reference docs? How to ensure docs discussion is productive at the language summit Not the nitty gritty about the past decisions Focus on role of Core team, PSF, vision Mention the Education \u0026amp; outreach WG Who are we serving, how do we serve them Main audiences: Docs community, Python users, new users What else core team expect from us? What do we want to achieve? Mariatta to start some slides (maybe not until May) Docs audit is still on hold. Might sprint at PyCon US. Review our Changelog: https://deploy-preview-28\u0026ndash;pythoneditorialboard.netlify.app/changelog/ https://github.com/python/editorial-board/pull/28 Actually, a lot has happened with Editorial board! ","permalink":"https://python.github.io/editorial-board/updates/2025-04-08-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: Apr 8, 2025","title":"Meeting Minutes: Apr 8, 2025"},{"content":"Agenda Docs audit with Savanna is on hold while she deals with other commitments https://github.com/python/editorial-board/issues/25 (translation management) (issue is closed) Notes Wiki: Carol went to Docs WG meeting last week. Discussion about the wiki. It is outside of EB’s focus. But we should not link to the wiki from Python docs. It would be great to have an Educational Landing page -\u0026gt; for a Python user, it would be better to have it instead of the wiki.python. Wiki is not a PSF-owned infrastructure? We have many links (~20) to the wiki from cpython repo. Most were old what’s new docs. We will update and unlink (?) Maybe write in Devguide about the status about wiki.p.o. It is a community-run resource, it has implied authority beyond its actual authority. Translations is doing well, now there is a translations dashboard https://python-docs-translations.github.io/dashboard/ Issue 25 is now closed, opened a Discourse instead https://discuss.python.org/t/pep-545-update-pep/83534/ There is now typing.python.org Why is it separate from docs.python.org? It’s maintained by typing council. A set of standards for type checkers (which are not maintained by Python core) Should we explain all the different (something).python.org -\u0026gt; specifically wiki and typing Add writeup in devguide about which ones are Core Python docs, and there are things like packaging. Should we add typing.python.org as “not in scope” in our charter doc? The typing.p.o docs aren\u0026rsquo;t tied to CPython version Carol received comment from a Linux conference attendee, last few Python releases have been easy to install. Ned is still going on with Devguide reorg (Initially we set a due date to get it done by PyCon US - PyCon US is in 2 months) “Or” vs “|” in the docs. Feb 11 notes: prefer | instead of “or”. We should write it to our changelog https://github.com/python/editorial-board/blob/main/CHANGELOG.md https://github.com/python/editorial-board/issues/7 It depends on the Sphinx’ capability. It is supported in latest Sphinx and docs are now built using latest Sphinx. Need to go back in our notes and backfill the Changelog.md file The Docs WG are to ask the PSF to pay for the translation tools. ","permalink":"https://python.github.io/editorial-board/updates/2025-03-11-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: Mar 11, 2025","title":"Meeting Minutes: Mar 11, 2025"},{"content":"Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/\nSummary Discourse topic: How should we mark up multiple types in a type field?\nCurrently, the Python docs use | (pipe) character, similar to how you\u0026rsquo;d annotate a union of types:\n:param p: A parameter that takes an int or a float argument. :type p: int | float However, the Sphinx docs says to use the word or:\n:param p: A parameter that takes an int or a float argument. :type p: int or float The editorial board\u0026rsquo;s decision was requested on this matter via issue #7.\nThe editorial board discussed this over several meetings, our decision is to use the | symbol. We met with Adam Turner to discuss how this would be implemented in Sphinx. This is supported in the latest version of Sphinx and the CPython docs have been built using the latest Sphinx.\n","permalink":"https://python.github.io/editorial-board/changelog/2025-03-11-pipes-or-in-sphinx-type-descriptions/","summary":"Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/\nSummary Discourse topic: How should we mark up multiple types in a type field?\nCurrently, the Python docs use | (pipe) character, similar to how you\u0026rsquo;d annotate a union of types:\n:param p: A parameter that takes an int or a float argument. :type p: int | float However, the Sphinx docs says to use the word or:\n:param p: A parameter that takes an int or a float argument.","title":"``|`` or 'or' in parameter documentation"},{"content":"History of dead batteries: https://discuss.python.org/t/history-of-dead-batteries/68934\nDocumenting Dead batteries: https://discuss.python.org/t/documenting-dead-batteries/70652\nPR: https://github.com/python/cpython/pull/126622\nSummary The PR adds a \u0026ldquo;Removed modules\u0026rdquo; page that lists modules which have been removed. Each module gets a page (with the original URL) that explains why the module is gone.\n","permalink":"https://python.github.io/editorial-board/changelog/2024-11-11-dead-batteries-docs/","summary":"History of dead batteries: https://discuss.python.org/t/history-of-dead-batteries/68934\nDocumenting Dead batteries: https://discuss.python.org/t/documenting-dead-batteries/70652\nPR: https://github.com/python/cpython/pull/126622\nSummary The PR adds a \u0026ldquo;Removed modules\u0026rdquo; page that lists modules which have been removed. Each module gets a page (with the original URL) that explains why the module is gone.","title":"Dead Batteries Docs"},{"content":"Agenda Doc audit https://github.com/sphinx-doc/sphinx/pull/13242 \u0026ndash; technicalities about \u0026lsquo;or\u0026rsquo; vs. \u0026lsquo;|\u0026rsquo; in Sphinx \u0026lsquo;:type:\u0026rsquo; constructs. There appears to be growing support for sticking with \u0026lsquo;|\u0026rsquo; Star/Slash in function signatures Notes Docs audit for argparse: see the “Docs Audit: argparse” doc in resources Looks like a good start Joanna and Savannah will be collaborating on this in the doc at first With some updates in the EB Discord They don’t currently need anything from the Board at the moment They will pull us in if needed Pipes vs “or” in Sphinx type descriptions? https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30 Adam Turner joins to help Adam’s view: we should adopt type annotation syntax When that doesn’t work (no type, or “file-like”, etc) we should leave the annotation blank, but still write out the English There are three places type information can appear: The function signature, which should look like Python code If an argument is “file like”, it should be omitted here. The argument bullet list This is the awkward place: types are parsed here with AST. Sphinx possibilities: Allow quoted strings, omit the quotes when rendering, and cross-link if the term is in the glossary. Try to parse with AST, if it fails, parse with tokenize English prose in paragraph form If an argument is “file like”, it should be fully described here. Plan: For non-formal types, use glossary cross-references Use pipes instead of prose where possible Implementation Allow quoted strings as the type annotation Unify parsing of field-list style and annotation-style Start with custom code for CPython to not have to wait for Sphinx release But goal is to upstream it to Sphinx Update the discuss.python.org thread with the decision. Star/Slash in function signatures We want signatures to be precise: if arguments are positional, use a slash, even if there is only one argument. We will experiment with Sphinx tooling to provide a link on the slash and star. We looked at underline for slash, it was distracting and drew attention to the slash, when most people argue that the slash is already too distracting Hover text is a good fallback if a link isn’t an option. ","permalink":"https://python.github.io/editorial-board/updates/2025-02-11-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: February 11, 2025","title":"Meeting Minutes: Feb 11, 2025"},{"content":"Agenda https://discuss.python.org/t/getopt-and-optparse-vs-argparse/69618/123 Notes Revisiting the “how to mark up types” discussion: https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/30 Erlend said “int or float” (our slight preference) would cause a syntax error for attributes in Sphinx. Ned’s quick experiment didn’t cause a syntax error Ned has pinged Erlend in Discord for a clarifying conversation. If it is a tooling issue, we will rule in favor of “int | float” Otherwise, we can rule for “int or float” https://discuss.python.org/t/getopt-and-optparse-vs-argparse/69618/123 Savannah mentioned an audit Joanna will respond on Discourse, inviting Savannah to participate in a docs audit of the argparse pages. Starting point: Two potential user journeys:\nMaking something more basic. Have flags, take in files Making something with subcommands, like git. How do you structure that? Make them part 1 and part 2 of a how-to? Main docs link to how-to(s) with user journeys + reference docs\nWe’ve long aspired to doing docs audits, this could be a good baby step It is small enough to be approachable It can be a way to educate people about what docs audits are and how to do them It can be a way for us to reach agreement on how we will do docs audits User personas How much of this is needed before starting an audit? ","permalink":"https://python.github.io/editorial-board/updates/2025-01-14-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: January 14, 2025","title":"Meeting Minutes: Jan 14, 2025"},{"content":"Notes Is what we’re doing fulfilling the purpose of the EB? We have been very casual We can be more proactive instead of waiting to be asked for a decision. Tables vs two-line summary: https://discord.com/channels/935215565872693329/935215566334079058/1313842986836037683 Indecisions about docs are blocking contributions Diataxis says to make plans and decisions, not sweeping changes Log of decisions: We have the changelog https://python.github.io/editorial-board/changelog/ People might want a one-size-fits-all decisions but Churns for docs is different with code churns Maybe we’d be more open to it? We can be more proactive instead of reactive Still mention that please don’t make PRs just to make sweeping changes to conform to the new styling decisions How to be more proactive: just be more active on the Docs discourse. We can say “the board discussed it and …” Docs audit? Get more of a plan on how to proceed from Joanna Docs needing fixing: Argparse, asyncio, Threading (incl. concurrent.futures) Request decision Request for decision: how should we mark up types in parameter lists? https://github.com/python/editorial-board/issues/7 Make it a formal decision: Use the word or instead of | Instead of | None, use “optional”? Use “default” instead of “optional” We are moving to Tuesdays Next meeting is Tuesday Jan 14 We should discuss docs issues more instead of personal projects ","permalink":"https://python.github.io/editorial-board/updates/2024-12-10-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: December 10, 2024","title":"Meeting Minutes: Dec 10, 2024"},{"content":"Agenda Contrib guide latest PR: https://github.com/python/devguide/pull/1467 What does Triaging mean? It’s a specific role with permissions Make the order of the columns: docs, code, triaging Keep pushing forward Removing dead batteries doc Discussion: https://discuss.python.org/t/documenting-dead-batteries/70652/10 PR: https://github.com/python/cpython/pull/126622 Reviewing what PEP 732 says about the structure of the PDEB ","permalink":"https://python.github.io/editorial-board/updates/2024-11-11-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: November 11, 2024","title":"Meeting Minutes: Nov 11, 2024"},{"content":"Refactoring the devguide into a Contribution Guide https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409\nSummary We\u0026rsquo;ve started a large task to restructure the devguide to be more welcoming to non-code contributions.\n","permalink":"https://python.github.io/editorial-board/changelog/2024-10-14-devguide-reorg/","summary":"Refactoring the devguide into a Contribution Guide https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409\nSummary We\u0026rsquo;ve started a large task to restructure the devguide to be more welcoming to non-code contributions.","title":"Devguide Reorganization"},{"content":"Agenda Contribution Guide progress Modernizing Python Docs Notes Contribution Guide progress\nPR created, approved. PR build: https://cpython-devguide\u0026ndash;1426.org.readthedocs.build/ PR: https://github.com/python/devguide/pull/1426 Status: There is a new section within the current Devguide: “(draft)” item on the left menu. How do we feel about it landing on main right now? Worried about people ending up in the draft accidentally and thought it’s the real one. There is an info box at the top of each contrib guide saying it’s a WIP. Example: https://cpython-devguide\u0026ndash;1426.org.readthedocs.build/contrib/intro/\tthere is a box at the top. [Ned TODO] Add the plan of this new contrib guide under “Introduction” [Ned TODO] embolden the section head in side bar also. How can people discover this? devguide.python.org/contrib Or look for the menu item Concerns with merging Linking concerns? Plan: flesh out the pages that don’t exist first. Then move things around later? We use Sphinx include directives. Make sure existing devguide maintainers and docs wg community take one last look Hugo, Jelle, Ezio, Petr DevGuide landing page, has a Quick Reference. It goes straight to code contribution. Feedback from people: it’s not relevant to doc contribution. Need a better pathway. Move the Quick reference to the code contribution. On the landing page there is the table for contribution paths, we can move that up. Instead of table with many rows, it could be a table with two rows and bullet lists. We could use tabs too? What’s the next steps after merging? Ned will write up the plan Talk to people mentioned above Merge the PR More todo items from above Get feedback from people interested in writing sections and see it grow Do people want to be “codeowners” on the new contrib guide? Maybe eventually Modernizing Python Docs (Mariatta)\nInspiration https://docs.astro.build tutorials.python.org built with new content and new tech What is the vision? Guido would like to see a smaller project using this new/other technology. We can frame it as “PDEB wants to try things out and will solicit feedback from the community.” Maybe take existing tutorials/how to and see how it works on this new tech. See also https://mystmd.org/ Alternative tech that has JS interactivity Start with a small prototype of a tutorial Slice tutorial? ","permalink":"https://python.github.io/editorial-board/updates/2024-10-14-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: October 14, 2024","title":"Meeting Minutes: Oct 14, 2024"},{"content":"Notes Discuss past action items. Catch up about last month: Outline about the DevGuide DevGuide GitHub project (who will create?) Write the issues (who will write?) Do we publish changes as they are ready, or do we wait until entire reorg is finished? What about existing URLs? (urls from other existing pages) Since we are on readthedocs, it can be mapped from there -\u0026gt; redirect to new pages You can mark pages as orphaned on Sphinx(?) Cam/Hugo might know Do we need to convince others about this approach? Publicize the fact that we are actively reorganizing the DevGuide into Contribution Guide (TODO: Ned will start a Discourse thread, and will send a link) Done https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409 Some things that document what’s changed between Python versions are better off in the same VCS as the code. Things in the current DevGuide are like that. So we need to define what belongs in Contrib Guide vs CPython docs. Example: Irit’s project is better documented within CPython’s doc. Tracked in https://github.com/python/cpython/issues/119786 We should go into detail: what our workflow is, and explain where to go for different docs, where are things documented. We like the idea of publishing in progress. Unsure about url remapping right away. Are we still using the “devguide” sub url? -\u0026gt; should it be “contributing” subdomain. “Devguide” is well known terminology among existing contributors. “Contributors” vs “contributing” . python org url -\u0026gt; can cause confusion when typing out the url We like “contrib” contrib.python.org is chosen as the new url. Ticket created at https://github.com/python/devguide/issues/1393 Adding a big banner on top saying this doc is being actively re-org. We might not want to render pages that are not really ready to be published. (by adding to conf.py ignores)? But also why not render those? When will we render those? Another idea: add new pages to main branch, add to “do not render” list, have 2 different rtd sites built using the same repo, different config. Sphinx has “if” conditional Who’s available and can do this work during the Sprint? Mariatta, Ned (remotely)? There will be a period of when both versions exist, and we want to keep this period short. Tools available to make both versions work. ","permalink":"https://python.github.io/editorial-board/updates/2024-09-09-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: September 09, 2024.","title":"Meeting Minutes: September 09, 2024"},{"content":"Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/\nSummary The Style Guide has been updated with new recommendations about author attribution (don\u0026rsquo;t include it) and pronunciation of dunder names (\u0026ldquo;an __init__, not a __init__).\n","permalink":"https://python.github.io/editorial-board/changelog/2024-08-28-style-guide-recs/","summary":"Additional recommendations in the Style Guide https://github.com/python/devguide/pull/1377/\nSummary The Style Guide has been updated with new recommendations about author attribution (don\u0026rsquo;t include it) and pronunciation of dunder names (\u0026ldquo;an __init__, not a __init__).","title":"Style Guide recommendations"},{"content":"Old Action Items Where are we with the action items from June 3?\nCreate a dir in the GitHub repo and move there? Move or link the docs to the GitHub repo? Communicate this at the next Docs Community meeting DONE: Ned will write up an outline for “How to contribute to CPython Docs” Finish up the Guiding Principles doc, and officially adopt it. To become the first page of the Docs Guide Form a WG to address packaging users docs Agenda What should we accomplish before our next call? Migrate documents from Google Drive to GitHub? Next steps for docs guide? Next steps for Guiding Principles doc? Next steps for wg to address packaging user docs? Notes We did not go through the planned agenda, but Mariatta and Ned discussed the new outline for DevGuide.\nNew outline for devguide / contribution guide Proposed outline for combined guide: https://docs.google.com/document/d/1Ajk_Vj3rccJ9ReB7WCNhEnLHQP23iMg7jAFQ-CYKzWo/edit\nNext steps: Create devguide project\nWrite devguide issues\nOverall restructure, with placeholder sections, according to the Google Doc. No need to write content. Placeholder pages can include bullets about the topics to be covered there. Placeholder pages can have a boilerplate info box explaining that the page is in-progress. Write issues for each section that needs to be fleshed out. Question: We propose to publish the new-organization skeleton as the devguide while we flesh it out. Ask in PDEB Discord if anyone objects. We want to keep it simple, so no branch, publish the placeholders\nIt will be for a short time Don’t want to maintain a long-lived branch Raises the visibility of the work Encourages contribution Set a target date for when this is done\nAim to have it done by May 2025 for PyCon US Maybe a sprint at PyCon to get it over the line ","permalink":"https://python.github.io/editorial-board/updates/2024-08-12-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: August 12, 2024.","title":"Meeting Minutes: August 12, 2024"},{"content":"Clarify timezone vs \u0026ldquo;time zone\u0026rdquo;: https://github.com/python/devguide/pull/1352\nSummary The CPython PR #118449 updates the spelling of \u0026ldquo;timezone\u0026rdquo; to \u0026ldquo;time zone\u0026rdquo;. There was a discussion on the PR that the \u0026ldquo;timezone\u0026rdquo; spelling is also acceptable and have been used within the CPython docs consistently. However, both Wikipedia and The Free Dictionary redirect \u0026ldquo;timezone\u0026rdquo; to \u0026ldquo;time zone\u0026rdquo;.\nUsing the two-word form \u0026ldquo;time zone\u0026rdquo; would help separate the concept from the \u0026ldquo;timezone\u0026rdquo; class in Python.\nThe Style Guide section on CPython Devguide has now been updated with the recommendation of using the two word time zone when referring to the real-world time concept, and to use the one word timezone with appropriate code markup when referring to a Python term.\n","permalink":"https://python.github.io/editorial-board/changelog/2024-07-18-clarify-timezone/","summary":"Clarify timezone vs \u0026ldquo;time zone\u0026rdquo;: https://github.com/python/devguide/pull/1352\nSummary The CPython PR #118449 updates the spelling of \u0026ldquo;timezone\u0026rdquo; to \u0026ldquo;time zone\u0026rdquo;. There was a discussion on the PR that the \u0026ldquo;timezone\u0026rdquo; spelling is also acceptable and have been used within the CPython docs consistently. However, both Wikipedia and The Free Dictionary redirect \u0026ldquo;timezone\u0026rdquo; to \u0026ldquo;time zone\u0026rdquo;.\nUsing the two-word form \u0026ldquo;time zone\u0026rdquo; would help separate the concept from the \u0026ldquo;timezone\u0026rdquo; class in Python.","title":"Timezone vs time zone"},{"content":"Function signatures should include slash and star: https://github.com/python/devguide/pull/1344\nSummary If a function accepts positional-only or keyword-only arguments, include the slash and the star in the signature as appropriate.\n.. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2): Although the syntax is terse, it is precise about the allowable ways to call the function and is taken from Python itself.\nThe CPython Devguide has been updated to reflect this recommendation.\n","permalink":"https://python.github.io/editorial-board/changelog/2024-07-12-function-signatures/","summary":"Function signatures should include slash and star: https://github.com/python/devguide/pull/1344\nSummary If a function accepts positional-only or keyword-only arguments, include the slash and the star in the signature as appropriate.\n.. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2): Although the syntax is terse, it is precise about the allowable ways to call the function and is taken from Python itself.\nThe CPython Devguide has been updated to reflect this recommendation.","title":"Function signatures include slash and star"},{"content":"Old Action Items Where are we with the action items from April 8?\nBring up in the next community call: Are there clear possibilities that you can share with the editorial board, so we can make a decision?\nNed has been attending, but can’t tomorrow. They have not been coming up with things they want us to do. Give them immediate feedback: we will decide if you create an issue. Sometimes the problem isn\u0026rsquo;t framed appropriately Carol will attend tomorrow. Todo: be clear to the docs wg that we will decide if you open up a ticket Eric Matthes said: wants to see us have more guiding principles before getting involved,\nTodo: create a dir in the GitHub repo and move there?\nGoogle Drive? Todo: move or link the docs to the GitHub repo NEW Action item: communicate the above to the next Docs Community meeting.\nWhere are we with the action items from March 11?\nLook at front page of docs.p.o and decide which ones should be more prominent Come up with a short: (3 page) tutorial. Carol will start an outline. Document our philosophy, explain the different target users and where they can find the docs they need. Agenda What action items are we taking from the discussion at the docs dinner?\nNotes on contributing to docs:\nMelanie’s notes: Python Docs Contributing Adventure Shauna’s notes: Python Docs Onboarding Notes Notes after discussion with Eric Matthes: Guiding Principles for Documentation Editorial Board.md Sprint ideas from Carol\u0026rsquo;s discussion: Doc ideas.md Other notes from dinner:\nShould you learn Python Cheatsheet for rST markup Ned says: \u0026ldquo;Write how-tos for Trey\u0026rdquo; Trey = priorities Docs are shared resource Add \u0026ldquo;Did you find this helpful\u0026rdquo; Update \u0026ldquo;How to contribute to docs\u0026rdquo; in dev guide and perhaps in a more user friendly way What to expect after a docs PR Codespell run once by core devs then add to CI after Message on PR template for docs that sets expectations for PR review Action item: no clear path for contributing to CPython Docs. Devguide section is lacking, mostly for CPython code changes.\nNew action item: the PDEB should write tickets for the action items on this meeting\nDecision:\nWe are sticking with Rst for CPython docs. Myst Parser: https://myst-parser.readthedocs.io/en/latest/ Mariatta has a talk: Introduction to Sphinx Docs and reStructuredText - Pyninsula #28 Action item:\nNed will write up an outline for “How to contribute to CPython Docs” What action items are we taking from the docs summit? none\nDo we have action items from the Docs Community?\nIs it time for us to focus on filling out these two docs so we can set a direction? Is there something else we should do first because it is either a higher priority or a prerequisite? Are there people in the Python community who have more formal experience with user research and might want to help?\nDiscovery doc about learners (Carol, would you like to capture your thoughts in this doc since you seem to have considered the issue deeply?) The Guiding Principles for Documentation Editorial Board.md captures the 3 user personas. Discovery doc about contributors (Ned, would you like to capture your observations about the community in this doc since you seem to be the most involved with them?) Action item: finish up the 🔒 Guiding Principles doc, and officially adopt it. To become the first page of the Docs Guide. To answer the “Discover Doc about Learners” Discovery Doc: Who is Our Learner Todo: form a WG to address packaging users docs\nDiscussing the Guiding Principles\nHow to ensure the novices are properly supported? Action item: Develop a user-journey. Tutorials, to be added outside of the actual Tutorials section. Eg including examples in references. Who are our contributors? Core devs. Code changes -\u0026gt; doc changes Long-term docs contributors Drive-by contributors Translations People writing dev docs professionally don’t wanna contribute to Open source docs? Educators may have feedback too As PDEb we can create a system to unblock contributors. Which type of contributors we want to focus on? #2: long-term docs contributors. Action item: the doc outline. Share tools/cheatsheet of learning Sphinx/rst, etc Note: the logistics of splitting up docs sections will be a big project Action item: Pull out docs-related from devguide as a (git) subtree There are a lot of undocumented Docs tooling. Should write it up? Next meeting: vacations, EuroPython.\nCancel July, and meet August 12. ","permalink":"https://python.github.io/editorial-board/updates/2024-06-03-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: June 03, 2024.","title":"Meeting Minutes: June 03, 2024"},{"content":"Agenda What will be our Doc Summit participation? Who will be attending? Carol, Ned Lightning talk: submit: https://docs.google.com/forms/d/e/1FAIpQLSe1n3YMIRnrWhoSSC29yM1w_IucgrY4D6RM3infhaNELFeJSg/viewform TODO: Carol will put together some bullets Prepare an “elevator pitch” kind of thing for Editorial Board: it could just point to our repo too? Advice: If you’re going to run a meeting, run the meeting (including cutting and moderating, stopping people from going on and on) Bring up in next community call: Are there clear possibilities that you can share with the editorial board, so we can make a decision. Carol or Ned to come up with the options. Warning Sphinx? Multiple types: https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196/20 TODO: Ned will post on the thread to try to come to closure. What are the current options? WarningMessage is undocumented: https://discuss.python.org/t/warningmessage-is-undocumented/48877 No meeting in May because of PyCon US. We’ll discuss async until June. ","permalink":"https://python.github.io/editorial-board/updates/2024-04-08-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: April 08, 2024.","title":"Meeting Minutes: April 08, 2024"},{"content":"Agenda What project do we want to deliver first? Here are some ideas to start the discussion:\na. Define scope and outline for new intro tutorial b. Define scope and outline for new landing page c. Inventory/audit a section of the docs d. Define learner personas\nWhat does the docs community need from us most right now? Here are some ideas to start the discussion:\nHow-to discussion First-person discussion A more thorough and more skimmable style guide [meta] Do we have a way to collect the largish topics they’ve discussed that we could provide guidance for? -\u0026gt; see editorial-board GH repo Function parameters: bulleted or not Examples: how to integrate into the docs Type hints Do we have an idea of what type of learner/user we need to optimize the docs for?\n🔒 Discovery doc about learners Thoughts about growth in users and approach Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?\nHow do we decide on issues for our agenda? Is e.g. https://github.com/python/cpython/pull/116595 suitable to discuss here?\nNotes Guido: We didn\u0026rsquo;t actually go through that agenda at all. We discuss what our priorities are. We also didn\u0026rsquo;t review last month\u0026rsquo;s action items.\nPython growth for the next decade will be driven by non CS folks, new users, non technical.\nExisting tutorial is the \u0026ldquo;what\u0026rdquo;\nPython has a rich ecosystem, you can get a lot of things done without needing the full scope of the stdlib. We should have more docs for it. Example docs:\nhttps://github.com/sandiegopython/intro-to-python/ Jessica McKellar’s intro: https://www.youtube.com/watch?v=rkx5_MRAV3A We need an introduction to Python docs. Current official Tutorial isn’t targeting new non-technical learners. They don’t know where to start. Other resources exist elsewhere. But it would be useful to have a beginner’s guide within docs.p.o\nDo we need to cover everything? Lots of people write guides to Python Official docs could have a curated list of useful docs. Options:\nBetter landing page? It needs to be better for newcomers, but also for people who are already experienced and already know their way around the docs. Come up with a refresh of the docs.python.org landing page, more user friendly and welcoming/inviting. Tooltips/ Guided tours -\u0026gt; need cookies. Just provide a link instead of interactive. Action item: Look at front page of docs.p.o and decide which ones should be more prominent Come up with a short: (3 page) tutorial. Carol will start an outline. Document our philosophy, explain the different target users and where they can find the docs they need. Glossary Define other user personas first? Docs community meeting. Anything we should know?\nWhat to do with Changelog. Directives changes in the rst. Need to improve the devguide for it. Typographic markups. Still under discussion on Discourse. Think about the outcome first and toolings next. Accessibility checking. UI/UX. Italics or not. Ned is talking to a university professor who is building their own IDE/notebook.\nThey see this as a hurdle for teaching Python to students ","permalink":"https://python.github.io/editorial-board/updates/2024-03-11-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: March 11, 2024.","title":"Meeting Minutes: March 11, 2024"},{"content":"Agenda What project do we want to deliver first? Here are some ideas to start the discussion:\na. Define scope and outline for new intro tutorial b. Define scope and outline for new landing page c. Inventory/audit a section of the docs d. Personas (see #3 below)\nWhat does the docs community need from us most right now? Here are some ideas to start the discussion:\nHow-to discussion First-person discussion A more thorough and more skimmable style guide [meta] Do we have a way to collect the largish topics they’ve discussed that we could provide guidance for? -\u0026gt; see editorial-board GH repo\nFunction parameters: bulleted or not Examples: how to integrate into the docs Type hints Do we have an idea of what type of learner/user we need to optimize the docs for?\nWait until Carol is back Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?\nWill the editorial board give an update at the language summit or PyCon?\nThe language summit isn’t even announced yet. We’ll think about it next time Notes Let’s begin with a relatively small project. 1b from above. It is concrete, and we can propose implementation and refine it quickly.\n2a is a bigger issue, but is important. (will affect 2b)\nRecommendation: don’t use first-person for new docs.\nHowto doc: we might preserve some historical content. Some docs may be marked as “historical doc”, keep them, but might get changed. Add a disclaimer at the top.\nAdd reminder to future contributors not to use those as a template.\nPR churn. Docs changes don’t need to follow the same guidelines.\nStyle guide:\nIn devguide now, update it https://devguide.python.org/documentation/style-guide/ Some things should be in the style guide First person, terminologies like master/slave, should be there Big O notation should be in the Howto part of the style guide The EB will own this (and create issues and PRs) Should still be on devguide Discovery: 🔒 Docs Style Guide\nMariatta to create a Gdrive folder to be shared with PDEB\nNeed an announcement about https://github.com/python/editorial-board, that we\u0026rsquo;re here. The readme should tell people how to be involved and how to ask for help.\nOn Discourse In the README of docs-community GitHub repo DevGuide And PEP 732 Docs Discord server: we shouldn’t need to be the owner.\nDiscuss: what type of learner we need to optimize the docs for?\nWe wait until Carol is back We’ll start an async collaboration in a new Google Doc There is a way to get notification of changes in Google Docs (need to be set up per-doc): Click the “comment” button Click the bell to set notifications: you can get notified of all content changes Do we have an idea of what type of contributor we want to prioritize removing obstacles for and creating systems for?\nWhat are the types of contributors? Core devs, triagers -\u0026gt; already know the way For non core devs: First time OS contributor, vs experienced OS contributor Non developers Not-primarily english-speaking contributors Guido’s request: Not having links that are hidden unless you hover\nA tutorial on how to successfully contribute to the CPython docs.\nCPython docs links to GitHub source code if clicked on the “Show Source” link. Is this good?\nSome pages get rendered (pprint.rst), some show as raw rst (functions.rst) What type of contributors who can make the biggest impact, that we are currently overlooking?\nTech writers Challenge: who to listen to. PR reviews can be noisy. Member vs Contributor But what if even core devs conflict with each other. Can we have volunteers/helpers to help people with pull requests?\nCould be similar to the Djangonauts: have someone who will help new contributors with PRs. Captains, navigators, etc Or less structured. Avoiding using the word “mentor” because it seems to be establishing a formal relationship Action items Style Guide: Update the style guide with some new recommendations: first-person, terminologies Ad campaign: More detail on #10 of the above notes:\nStart the async exploration of who our learners are Start the async explorations of what kind of contributors we want to help Specify that Python wiki is out of scope in PEP 732: https://github.com/python/peps/pull/3663 ","permalink":"https://python.github.io/editorial-board/updates/2024-02-12-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: February 12, 2024.","title":"Meeting Minutes: February 12, 2024"},{"content":"Agenda We discussed these questions and worked to answer them.\nHow often will we meet? We will meet monthly on second Monday each month from 1:30-2:30pm Pacific.\nWe will work asynchronously most of the time.\nNext meeting: February 12, 2024\nWhat are our deliverables about process and decisions? We will produce:\nMeeting Minutes: Working meeting notes will be summarized and published in repo after each meeting. Process and priorities Decisions will be published in \u0026ldquo;Recommendation\u0026rdquo; documents. These would be short documents focused on one topic. They would be published in the repo. Identify what the needs are for the specific section of docs. So that greater community can know the goals when they do sprints etc. We can identify blocking factors and remove them. We write outlines, and the community can write the content. It’s good because it encourages writing new docs instead of modifying existing ones. There have been a lot of big overhaul projects that got swamped by discussions. Agenda gathering for next meeting: Use an issue on the GitHub repo. Focus on content needs and improvements; tone and style guides (not restructuredText style but writing) From the docs landing page, do an annual assessment of each part and identify need/frequency of changes (could be the foundation of a high-level editorial calendar of needs - one section each month) Idea: incorporate algolia search to sphinx Python.org vs docs.python.org We should limit ourselves to docs.python.org Share recommendations to python.org for changes about making sure on python.org docs will go to docs.python.org. Reduce multiple paths to wiki and doc landing pages other than docs.python.org when refering to \u0026ldquo;docs\u0026rdquo; Will we start implementing the five-year plan partly outlined in the Language Summit 2020 presentation, or do we need to reassess and set a different direction? The goals mentioned in the first and second years sound great, but I think we should review and see what we want to tackle first. It could be those goals, or other ones, or a mix.\nYear 1 goals (from old presentation) Governance and Workgroup: In progress; TODO: define how we work Tutorials: Discussion started about existing tutorial. TODO: Do we have one \u0026ldquo;official\u0026rdquo; tutorial? Pathways for getting started (relates to landing page) Language Translations: Seems to be going well; TODO: Identify any PyCon sprint focus areas Landing Page: Work in progress Documentation Experience presentation TODO: Work with PSF to remove links to old wiki. This is for many the first stop in finding Python docs. Year 2 and beyond goals (from old presentation) Evaluate effectiveness Documentation sprints Annual editorial review Selected priorities for the Editorial Board How we can make it easier for people to contribute to docs How to make the docs even more accessible Modernizing the docs: content, UX, or the mechanics? Editorial board should lead the content priorities Color change, theme, community can do it. (They probably should have a PEP tp the SC for major changes.) Better SEO Process for the community to ask and bring proposals to EB Let\u0026rsquo;s model this after the SC process Encourage more positive and constructive discussions in the Python docs community. Work to reduce lengthy arguments, which are sometimes hostile and dismissive. When disagreements are at an impasse, make decisions to reduce those blockages. Decisions about documentation can be undone more easily than with code.\nHow will we stay in touch with the docs community? Some people have already asked how they can be involved.\nGenerally, people want to help with writing documentation, so they should be involved with the docs community and not editorial board.\nPublished meeting minutes. Clear \u0026ldquo;how to contact\u0026rdquo; us.\nWe will create the Repo and issue templates.\nIndividuals can create an issue to request the topic be added to the agenda. We will discuss at the next scheduled meeting time or asynchronously.\nCan people attend these Editorial Board meetings?\nNo. We will use a similar process as the SC.\nWe discussed the following process considerations:\nRepo is public, but not meant for public discussions.\nAvoid situation where there are many open issues.\nPrefer discussion on Discourse with Documentation tag, instead of on the Editorial Board repo.\nIssue on the Editorial board will lead to discussions on that issue. Is that ok?\nWe will follow the existing SC process:\nHave discussion on Discourse first then link the to an issue on the Editorial Board repo. Any further discussions to continue on the Discourse, or privately by the Editorial Board. There is no further discussions/comments on the repo\u0026rsquo;s issue. What are the things that require the Editorial Board to act on? Conflicts on content Conflicts on tone and style best practices Review of existing documentation and outline editorial needs Identify needs for new content Identify needs for rewrites Provide guidance and guidelines for changes See for example, the recent pull request: https://github.com/python/cpython/pull/107449/files which touches on global style issues. Action items Contact PSF infra/PSF board about python.org. Create a REPO similar to steering-council: python/editorial-board Readme should point to the PEP for Editorial board to create. @Carol to add content. Meeting notes: don’t need to include too much details. It doesn’t need review, comments. Let’s create a new repo: python/editorial-board. Done. @editorial-board team was also created. Need an issue template: on GitHub Need to submit their request into one of two big priorities: Proposing a new idea We need a decision of existing issue. Resources These links give context on the editorial board:\nPEP 732 PEP 732 Discourse discussion Language Summit 2021 presentation Language Summit 2020 presentation These links give context on existing landing pages:\nCPython Documentation Landing page (docs.python.org) PSF (python.org) website landing page Documentation Experience presentation [Work in Progress: Review of PSF landing page for docs] ","permalink":"https://python.github.io/editorial-board/updates/2024-01-08-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: January 8, 2024.","title":"Meeting Minutes: January 8, 2024"}]