[{"content":"Notes Team membership details: Guido is stepping down. What is the mechanism to get a new team member? It\u0026rsquo;s in the PEP: PEP 732 — Editorial Board Member Qualifications If a vacancy exists on the board for any reason, the Documentation Editorial Board will publicly announce a call for prospective board members. Prospective board members would submit a brief document stating qualifications and their motivation to serve. The sitting members of the Editorial Board will select new board members by a simple majority where quorum is 80% of the current board.\nBefore getting a new team member, do we talk more about our purpose or goals first? To set up an application form, we first need to clarify the expectations and roles so people know what they\u0026rsquo;re applying for. Different directions as the EB: Be more reactive: we\u0026rsquo;re here, we can help if you need us. Be more proactive: create initiatives, have ambitions, goals. Identify significant work that needs to get done, then lead/project-manage/shepherd, and find people to do those (outreach). Possible stances for EB members: Be available to make big decisions (be like the Steering Council, but for docs). Start and carry out significant work (this is more a core-team role, not an SC-style role). Identify big projects, reach out to find others to do the work, and lead them. If we go with option 3, we need to be ready to \u0026ldquo;project-manage\u0026rdquo; these ideas, and not just list the ideas. Requirement: a project will be listed only if there is a committed team lead for it. But what is the requirement to be a team lead, and what kind of commitment? What exactly does team lead/project lead mean? It should not be just a laundry list of things we want, but should also identify challenges related to the project. Docs WG meeting: review the notes. Need to review and come up with a list of projects for contributors to work on. Do we make a long list and let people find something that excites them? That might stretch our oversight efforts too thin. Or do we make a short list of our prioritized wishes? Projects should be described with details of what the challenges might be. To be successful, we need to find committed workers and be committed ourselves to the project. Write up expectations about being on the board. Hoping to get a new team member in Sept/Oct. Aim to get the word out by the next meeting. ","permalink":"https://deploy-preview-41--pythoneditorialboard.netlify.app/updates/2026-06-09/","summary":"Meeting Minutes from Python Docs Editorial Board: Jun 9, 2026","title":"Meeting Minutes: Jun 9, 2026"},{"content":"Notes Reviewed the doc structure in the datetime reference doc because Carol and Guido weren\u0026rsquo;t here last month. Discussion about redirects in the Docs WG. According to Petr, he can handle redirects. We don\u0026rsquo;t know the technical details of how the redirect will happen. It\u0026rsquo;s OK if we go ahead with splitting the page, and Petr said he will handle it. He said it will be addressed in the redirection PR. Other work in Docs might also be blocked because they want redirects. How would we want to split up the datetime doc? Split into different classes? Date and datetime are relevant. What other modules have different pages split up? Generally, it will be better to split up docs anyway. To help with SEO and LLMs finding data, it works better with more focused docs. We may want to argue for breaking up module docs based on certain criteria. Split up format codes (it already says \u0026ldquo;Skip to the format codes\u0026rdquo;). We want to see this split up. Talk to Paul Ganssle first about timezone classes? datetime.rst is in the top 10 of largest files. Mariatta\u0026rsquo;s PR #125009 and follow-up PR from Stan #132524. Splitting the datetime doc: Start by removing the format codes. In Mariatta\u0026rsquo;s PR, make notes 10 and 11 separate directives — not part of the table notes. The code change can be in a separate PR. Discuss the redundancy of the Editorial Board. Next meeting is during PyCon US, we will be occupied. Cancel the May meeting. Keep June. Discuss meeting cadence and membership in July. ","permalink":"https://deploy-preview-41--pythoneditorialboard.netlify.app/updates/2026-04-14/","summary":"Meeting Minutes from Python Docs Editorial Board: Apr 14, 2026","title":"Meeting Minutes: Apr 14, 2026"},{"content":"Notes Any news? Ned was at the community meeting last week. The group agrees with keeping import datetime as dt and keeping it in the docs. The datetime doc is messy and lengthy. The Notes have 10 notes. Inconsistent use of versionchanged, versionadded, etc. Mariatta and Stan have an open PR for adding note number 11, but now think it is not the right way to do it. It needs a rework. How do we approach this? Is this a similar pattern elsewhere? strftime and strptime format codes What can the EB do about this page? Footnotes are bad (if used incorrectly). Encourage better doc practice. Are there other styles in the Python docs that use this style of \u0026ldquo;notes\u0026rdquo;? struct docs for format characters stdtypes.rst Can we split this doc into various pages? Do you have the date-time to do it? (hehe) There is precedent where Jelle split up the C-API docs. Maybe start by opening a new issue about it. URLs will break; we can ensure there is a redirect. Any further thoughts about the EB? Sphinx-extensions issue that might need a decision from the EB. The discussion about underlining URLs in Sphinx docs: Should not underline links Ned built a linter that cleans up excessive links in the Python doc. There is a link to the int doc everywhere. Is this bad? Should we keep it? ","permalink":"https://deploy-preview-41--pythoneditorialboard.netlify.app/updates/2026-03-10/","summary":"Meeting Minutes from Python Docs Editorial Board: Mar 10, 2026","title":"Meeting Minutes: Mar 10, 2026"},{"content":"Notes Discussed whether we should still act as the Editorial Board (EB) EB members\u0026rsquo; bandwidth: Low bandwidth, personal travels, etc. Suggestion: take it back to the Steering Council — do we have a need for it now? The charter was to unblock what was blocked Not many things are blocked these days Example issue: on Discourse, a topic about whether we should underline links Often we didn\u0026rsquo;t need to come in to state that we are in the EB We could still exist but we are a light load We could do quarterly meetings and chat on Discord as needed If the point is to unblock — is the reason we haven\u0026rsquo;t been needed because there are no issues/conflicts? From the Docs WG meeting: Tooling (issue with links) Links within our docs Links from outside to our docs If we reorg our docs (splitting a page into different pages), existing links from external sources to our docs are now broken Petr is looking into fixing it Links from our docs to external docs The fact that we exist is a good thing. Things seem smooth right now. May want to look into the Free-threading group. They may have similar challenges with docs. There may not be clarity about the expectation of what should be documented. Example: the memory model isn\u0026rsquo;t documented. Should the time complexity be in the Python docs? Conclusion: Continue to exist Scale back expectations Continue the monthly cadence Review if any of us want to take a step back and open up the space for others to come in ","permalink":"https://deploy-preview-41--pythoneditorialboard.netlify.app/updates/2026-02-10/","summary":"Meeting Minutes from Python Docs Editorial Board: Feb 10, 2026","title":"Meeting Minutes: Feb 10, 2026"},{"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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/changelog/2025-03-11-pipes-or-in-sphinx-type-descriptions/","summary":"\u003cp\u003eAdditional recommendations in the Style Guide \u003ca href=\"https://github.com/python/devguide/pull/1377/\"\u003ehttps://github.com/python/devguide/pull/1377/\u003c/a\u003e\u003c/p\u003e\n\u003ch2 id=\"summary\"\u003eSummary\u003c/h2\u003e\n\u003cp\u003e\u003ca href=\"https://discuss.python.org/t/how-should-we-mark-up-multiple-types-in-a-type-field/48196\"\u003eDiscourse\u003c/a\u003e topic: How\nshould we mark up multiple types in a type field?\u003c/p\u003e\n\u003cp\u003eCurrently, the Python docs use \u003ccode\u003e|\u003c/code\u003e (pipe) character, similar to how you\u0026rsquo;d annotate a union of types:\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-rst\" data-lang=\"rst\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e:param p:\u003cspan class=\"err\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e   A parameter that takes an int or a float argument.\u003cspan class=\"err\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nc\"\u003e:type p:\u003c/span\u003e \u003cspan class=\"nf\"\u003eint | float\u003c/span\u003e\u003cspan class=\"err\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003eHowever, the \u003ca href=\"https://www.sphinx-doc.org/en/master/usage/domains/python.html#send_message\"\u003eSphinx docs\u003c/a\u003e says to use the word \u003ccode\u003eor\u003c/code\u003e:\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-rst\" data-lang=\"rst\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e:param p:\u003cspan class=\"err\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e   A parameter that takes an int or a float argument.\u003cspan class=\"err\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"nc\"\u003e:type p:\u003c/span\u003e \u003cspan class=\"nf\"\u003eint or float\u003c/span\u003e\u003cspan class=\"err\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003eThe editorial board\u0026rsquo;s decision was requested on this matter via \u003ca href=\"https://github.com/python/editorial-board/issues/7\"\u003eissue #7\u003c/a\u003e.\u003c/p\u003e","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://deploy-preview-41--pythoneditorialboard.netlify.app/changelog/2024-11-11-dead-batteries-docs/","summary":"\u003cp\u003eHistory of dead batteries: \u003ca href=\"https://discuss.python.org/t/history-of-dead-batteries/68934\"\u003ehttps://discuss.python.org/t/history-of-dead-batteries/68934\u003c/a\u003e\u003c/p\u003e\n\u003cp\u003eDocumenting Dead batteries: \u003ca href=\"https://discuss.python.org/t/documenting-dead-batteries/70652\"\u003ehttps://discuss.python.org/t/documenting-dead-batteries/70652\u003c/a\u003e\u003c/p\u003e\n\u003cp\u003ePR: \u003ca href=\"https://github.com/python/cpython/pull/126622\"\u003ehttps://github.com/python/cpython/pull/126622\u003c/a\u003e\u003c/p\u003e\n\u003ch2 id=\"summary\"\u003eSummary\u003c/h2\u003e\n\u003cp\u003eThe 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.\u003c/p\u003e","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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/changelog/2024-10-14-devguide-reorg/","summary":"\u003cp\u003eRefactoring the devguide into a Contribution Guide \u003ca href=\"https://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409\"\u003ehttps://discuss.python.org/t/refactoring-the-devguide-into-a-contribution-guide/63409\u003c/a\u003e\u003c/p\u003e\n\u003ch2 id=\"summary\"\u003eSummary\u003c/h2\u003e\n\u003cp\u003eWe\u0026rsquo;ve started a large task to restructure the devguide to be more welcoming to non-code contributions.\u003c/p\u003e","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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/changelog/2024-08-28-style-guide-recs/","summary":"\u003cp\u003eAdditional recommendations in the Style Guide \u003ca href=\"https://github.com/python/devguide/pull/1377/\"\u003ehttps://github.com/python/devguide/pull/1377/\u003c/a\u003e\u003c/p\u003e\n\u003ch2 id=\"summary\"\u003eSummary\u003c/h2\u003e\n\u003cp\u003eThe \u003ca href=\"https://devguide.python.org/documentation/style-guide/\"\u003eStyle Guide\u003c/a\u003e has been updated with new\nrecommendations about author attribution (don\u0026rsquo;t include it) and pronunciation of dunder names (\u0026ldquo;an \u003ccode\u003e__init__\u003c/code\u003e, not \u003ccode\u003ea __init__\u003c/code\u003e).\u003c/p\u003e","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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/changelog/2024-07-18-clarify-timezone/","summary":"\u003cp\u003eClarify \u003ccode\u003etimezone\u003c/code\u003e vs \u0026ldquo;time zone\u0026rdquo;: \u003ca href=\"https://github.com/python/devguide/pull/1352\"\u003ehttps://github.com/python/devguide/pull/1352\u003c/a\u003e\u003c/p\u003e\n\u003ch2 id=\"summary\"\u003eSummary\u003c/h2\u003e\n\u003cp\u003eThe CPython PR \u003ca href=\"https://github.com/python/cpython/pull/118449\"\u003e#118449\u003c/a\u003e updates the spelling of \u0026ldquo;timezone\u0026rdquo; to \u0026ldquo;time zone\u0026rdquo;.\nThere was a discussion\non the PR that the \u0026ldquo;timezone\u0026rdquo; spelling is also acceptable and have been used within the CPython docs\nconsistently. However, both Wikipedia and The Free Dictionary redirect \u0026ldquo;timezone\u0026rdquo; to \u0026ldquo;time zone\u0026rdquo;.\u003c/p\u003e\n\u003cp\u003eUsing the two-word form \u0026ldquo;time zone\u0026rdquo; would help separate the concept from the \u0026ldquo;timezone\u0026rdquo; class in Python.\u003c/p\u003e\n\u003cp\u003eThe \u003ca href=\"https://devguide.python.org/documentation/style-guide/#style-guide\"\u003eStyle Guide\u003c/a\u003e section on CPython Devguide has\nnow been updated with the recommendation of using the\ntwo word \u003ccode\u003etime zone\u003c/code\u003e when referring to the real-world time concept, and to use the one word \u003ccode\u003etimezone\u003c/code\u003e with\nappropriate code markup when referring to a Python term.\u003c/p\u003e","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://deploy-preview-41--pythoneditorialboard.netlify.app/changelog/2024-07-12-function-signatures/","summary":"\u003cp\u003eFunction signatures should include slash and star: \u003ca href=\"https://github.com/python/devguide/pull/1344\"\u003ehttps://github.com/python/devguide/pull/1344\u003c/a\u003e\u003c/p\u003e\n\u003ch2 id=\"summary\"\u003eSummary\u003c/h2\u003e\n\u003cp\u003eIf a function accepts positional-only or keyword-only arguments, include the\nslash and the star in the signature as appropriate.\u003c/p\u003e\n\u003cdiv class=\"highlight\"\u003e\u003cpre tabindex=\"0\" class=\"chroma\"\u003e\u003ccode class=\"language-rst\" data-lang=\"rst\"\u003e\u003cspan class=\"line\"\u003e\u003cspan class=\"cl\"\u003e\u003cspan class=\"p\"\u003e..\u003c/span\u003e \u003cspan class=\"ow\"\u003efunction\u003c/span\u003e\u003cspan class=\"p\"\u003e::\u003c/span\u003e some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):\u003cspan class=\"err\"\u003e\n\u003c/span\u003e\u003c/span\u003e\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\u003c/div\u003e\u003cp\u003eAlthough the syntax is terse, it is precise about the allowable ways to call\nthe function and is taken from Python itself.\u003c/p\u003e\n\u003cp\u003eThe CPython Devguide has been updated to reflect \u003ca href=\"https://devguide.python.org/documentation/style-guide/#function-signatures\"\u003ethis recommendation\u003c/a\u003e.\u003c/p\u003e","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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/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://deploy-preview-41--pythoneditorialboard.netlify.app/updates/2024-01-08-editorial-board-update/","summary":"Meeting Minutes from Python Docs Editorial Board: January 8, 2024.","title":"Meeting Minutes: January 8, 2024"},{"content":" Status: Draft. This page is a work in progress, started following the June 2026 meeting. It describes what we expect of Editorial Board members and how the board chooses to operate. Comments and suggestions are welcome via an issue.\nPurpose The Python Documentation Editorial Board exists to maintain and improve the quality of Python\u0026rsquo;s documentation, as established in PEP 732. PEP 732 defines our mandate, scope, responsibilities, and membership rules; this page does not restate the PEP but instead records how the board chooses to work within it.\nHow we work: proactive, not just reactive The board considered three possible stances for how members spend their time:\nReactive — be available to make big decisions when asked (act like a \u0026ldquo;Steering Council for docs\u0026rdquo;). Hands-on — start and personally carry out significant work (closer to a core-team contributor role than a council role). Proactive — identify big documentation projects, reach out to find people to do the work, and lead/shepherd those efforts. We have chosen to focus on stance 3. Rather than waiting for issues to be escalated to us, the board will actively identify significant documentation work, find and support contributors to take it on, and project-manage those efforts to completion.\nWe remain available for the reactive decision-making in stance 1 — when the community needs the board to make a big-picture or tie-breaking decision about the docs, we are here to do so. In practice, though, this has rarely been needed: most documentation questions resolve without the board having to step in. Because that reactive load is light, our primary focus is the proactive work described above.\nWhat this means in practice:\nWe maintain a list of projects that we believe are worth doing. A project is listed only if there is a committed lead for it. The list is not a wish list — every entry has someone accountable for moving it forward. Each project is described with enough detail to be actionable, including the challenges and risks involved, not just the desired outcome. We hold ourselves to project-managing these efforts, not merely naming them. Member expectations Members of the Editorial Board are expected to:\nAttend the monthly board meeting (second Tuesday, 1:30pm Pacific) where possible, and stay engaged asynchronously on Discord between meetings. Help identify and prioritize documentation projects. Lead or actively shepherd at least one project, or support fellow members who are leading projects. Engage constructively with the wider documentation community (the Documentation Working Group, translation teams, and contributors). Confirm annually whether they wish to continue serving, per PEP 732. What it means to lead a project TODO: define the commitment expected of a project lead — e.g. defining scope, breaking the work into contributable pieces, recruiting and supporting contributors, reporting progress to the board, and seeing the work through.\nJoining the board The process for filling a vacancy is defined in PEP 732 under Editorial Board Member Qualifications:\nIf a vacancy exists on the board for any reason, the Documentation Editorial Board will publicly announce a call for prospective board members. Prospective board members would submit a brief document stating qualifications and their motivation to serve. The sitting members of the Editorial Board will select new board members by a simple majority where quorum is 80% of the current board.\nBefore opening a call for new members, the board will publish clear expectations (this page) so prospective members understand what they are signing up for.\nTODO: link to the application form / call for members once it is open.\n","permalink":"https://deploy-preview-41--pythoneditorialboard.netlify.app/expectations/","summary":"What we expect of Editorial Board members, and how the board operates.","title":"Board Expectations \u0026 Roles"},{"content":" Status: Draft. This page is a work in progress, started following the June 2026 meeting.\nThis is the Editorial Board\u0026rsquo;s list of significant documentation projects we are actively leading or shepherding. It reflects our proactive stance: rather than only reacting to requests, we identify important work and find people to carry it out.\nHow this list works Every project has a committed lead. This is not a wish list. A project is added only when someone has agreed to lead it. If a project loses its lead, it moves to Parking lot until a new lead steps up. Each project names its challenges, not just the goal. Describing the hard parts up front helps contributors know what they are taking on. We keep the list short and prioritized rather than long and aspirational, so we can give each project real oversight. Want to help with a project, or propose a new one? Open an issue on this repo or reach out in the Python Docs Discord.\nProject template Once a project is approved by the Editorial Board, copy this block to add a new project.\n### \u0026lt;Project name\u0026gt; - **Lead:** \u0026lt;name — required; no lead, no listing\u0026gt; - **Status:** Proposed | Active | Blocked | Done - **Summary:** One or two sentences on what this project delivers. - **Why it matters:** Who benefits and why this is worth doing now. - **Challenges / risks:** The hard parts — technical blockers, dependencies, unknowns, things that could derail it. - **How to help:** Concrete ways a contributor can get involved. - **Links:** Relevant issues, PRs, discussions, or docs. Active projects None listed yet. Add projects here using the template above.\nParking lot Ideas worth doing that do not yet have a committed lead. These are not active projects until someone steps up to lead them.\nEmpty for now.\n","permalink":"https://deploy-preview-41--pythoneditorialboard.netlify.app/projects/","summary":"Documentation projects the Editorial Board is leading or shepherding.","title":"Projects"}]