From f7c543492e035c648a7a4d499bebff0d558644bf Mon Sep 17 00:00:00 2001 From: Unique-Usman Date: Wed, 3 Jan 2024 22:56:24 +0530 Subject: [PATCH 01/10] Update docs/monthly-meeting/2024-01.md --- docs/monthly-meeting/2024-01.md | 127 ++++++++++++++++++++++++++++++++ docs/monthly-meeting/index.rst | 1 + 2 files changed, 128 insertions(+) create mode 100644 docs/monthly-meeting/2024-01.md diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md new file mode 100644 index 0000000..4903b2a --- /dev/null +++ b/docs/monthly-meeting/2024-01.md @@ -0,0 +1,127 @@ +# Documentation Community Team Meeting (January 2024) + +- **Date:** 2024-01-02 +- **Time:** [20:00 UTC](https://arewemeetingyet.com/UTC/2024-01-02/20:00/Docs%20Meeting) +- **This HackMD:** https://hackmd.io/@encukou/pydocswg1 +- [**Discourse thread**](https://discuss.python.org/t/42191) (for January) +- [**Meeting reports**](https://docs-community.readthedocs.io/en/latest/monthly-meeting/) (the latest one might be an [**unmerged PR**](https://github.com/python/docs-community/pulls)) +- **Calendar event:** (send your e-mail to Mariatta for an invitation) +- **How to participate:** + - Go to [Google Meet](https://meet.google.com/dii-qrzf-wkw) and ask to be let in. + - To edit notes, click the β€œpencil” or β€œsplit view” button on the [HackMD document](https://hackmd.io/@encukou/pydocswg1). You need to log in (e.g. with a GitHub account). + +By participating in this meeting, you are agreeing to abide by and uphold the [PSF Code of Conduct](https://www.python.org/psf/codeofconduct/). +Please take a second to read through it! + + +## Roll call + +(Name / `@GitHubUsername` *[/ Discord, if different]*) +- Carol Willing / `@willingc` / carolwilling +- Petr Viktorin / `@encukou` +- Ezio Melotti / `@ezio-melotti` +- Hugo van Kemenade / `@hugovk` +- Guido van Rossum / `@gvanrossum` +- Daniele / `@EvilDMP` / danieleprocida +- Ege Akman / `@egeakman` +- Ned / `@nedbat` +- Ryan / `@ryan-duve` +- Jim / `@JDLH` +- CAM / `@CAM-Gerlach` +- Usman Akinyemi / `@Unique-Usman` +- Bradley / `@shenanigansd` + +## Reports and celebrations + +> 60 second updates on things you have been up to, questions you have, or developments you think people should know about. Please add yourself, and if you do not have an update to share, you can pass. + +> This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We'll read through these at the beginning of the meeting. + +* The Steering Council has [accepted](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9?u=hugovk) [PEP 732](https://peps.python.org/pep-0732/) ("The Python Documentation Editorial Board") πŸŽ‰ + + - [willingc] First meeting will be January 8, 2024. + - [Carol] Looing at docs and website from a new user's perspective + - [Hugo] What would be the best way to contact the Board? [Guido] That's already on the agenda. [Carol] For the short term we could use the docs community repo too. + +* I [Jim] appreciate how considerate this group is. The particular incident motivating my appreciation is that I got mentioned in the minutes of last meeting, and several people took pains to be sure that my name was presented there as I wanted it to be. Thank you. + +* [Ryan] We made the update to the TOML documentation we talked about on the last call and got my first Python pull request merged! + +## Discussion + +- [Petr] Inclusive language + + The `tkinter`, `pty`/`termios`, `sqlite3` (maybe more?) use `master/slave` terminology in API and docs. What's the best way to come up with, and switch to, better terms? + + Is there an expert* I should talk to? + + - [willingc] Thursday Bram has authored a Responsible Communications book which may have helpful guidelines. Other communities have used `leader/follower`. [Linux PR on the subject](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb) + - [Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (willingc: I like the suggestions in this document for different usages.) + - [CAM] Earlier BPO issue: [python/cpython#78786](https://github.com/python/cpython/issues/78786) + + - To do + - Check and update the dev guide for new docs not to use terms and suggest alternatives + - Determine process for future changes of existing terminology + - Consider adding a statement to the documentation about existing code + - Petr will bounce ideas off Daniele :) + + +- Ryan tried introducing argument lists (like in [sqlite3](https://docs.python.org/3/library/sqlite3.html#sqlite3.connect)) to the collections module, didn't work too well as the functions take one or two args and they're pretty obvious. Petr recommended looking at `subprocess.Popen`. + - [willingc] Ryan, feel free to ping me when you have an example since I'm very familiar with the scientific python docs. + - Guido doesn't like forcing people to stick to a template + - Daniele mentions there are two kinds of users, one of which -- a forensic analyst -- could need very strictly formatted documentation + - [Guido] The bulleted list makes it less likely to fit everything on a screen. Vertical space is a precious resource. + - [Carol] Doc usage has changed thanks to intellisense, nowadays you get lists of arguments on hovering. + - [Carol] Areas where users ask for help most should get most attention + - [Ezio] There is some value in a consistent format for return values and exceptions; sometimes it's hard to find them currently. Arguments are usually explained well in the description. + - [Daniele] It doesn't need to be machine-readable. It should always be maximally human-comfortable. + - [Jim] It sounds like the framing of this discussion is, source text targetting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion? + - [Ned] We write docs twice -- once for the docstrings and once in `rst`. That's more work, but it means we can have different strategies for each use case. [Guido] Changing that would involve several PEPs. + - [CAM] Sphinx has ways to generate docs for a whole module, or just a single function, from docstrings. But yes, starting to use that would need a PEP. + - [CAM] The strategy we took for `sqlite3` was to focus on the functions with most arguments, where the bulleted lists have most benefit, and leave the smaller functions for later, when we have more experience with the approach. + - [Carol] And we should keep in mind that our perspectives are not necessarily the users' perspective. If we do make major changes we should think about users and we should vet the changes. + - Ryan started contributing by trying to get the contract of [`collections.Counter.most_common`](https://docs.python.org/3/library/collections.html#collections.Counter.most_common), and not finding it in the docstring nor in the documentation. + - Carol: If you're coming from the scientific world, where the `?` in IPython gives you the docstring, that is often the first thing you look at. + - Ryan will take a look at only documenting return type and "raises" in a structured way, leaving parameters in the prose. + - Guido warns that `collections.Counter` is not that typical. + +- If we have time, would like to hear from Daniele on the [thread he started on the structure of the Python docs](https://discuss.python.org/t/diataxis-and-python-documentation/41836) as to the takeways from that so far and next steps there. + + - Discussion between Daniele and Ezio on the Python tutorial + +- [Ezio] The docs for builtin functions doesn't have any examples. Idea: Add a separate page with 1-3 examples for each function. +- [Carol] always goes back to the users and what their pathways and needs are. The tutorial can't fit all users -- absolute beginners, people for whom Python is the first language, people coming from other languages. The current tutorial doesn't work for completely new users. +- [CAM] The current tutorial targets people who are already familiar with programming languages. Perhaps we should have separate tutorials for complete beginners and people coming from specific languages. +- [Daniele] One drawback of the current tutorial is lots of preamble saying why you want to learn Python. But the user is already here, wanting to learn Python. We should start directly with the examples. Also, we don't need to cover the edge cases right after people do something for the first time. Long explanations detract from the tutorial. +- [Ezio] It seems that for the tutorial, examples work better than prose, for both new and experienced users. Also, we could have cheatsheets for people coming from other languages. +- [Carol] There's a bigger pressing need for onboarding people from different groups, like people who don't know how to use the command line. + + +## Follow-ups from previous meeting(s) + +- [Ryan] standard library documentation reference and adding types to it in a structured way. For example, `collections.Counter.most_common` could be written + + most_common(n: int) -> list[tuple[Any, int]] + + [Petr] ... or `list[tuple[KeyType, int]]`? + + - this has been discussed. There was opposition to adding the types to the stdlib code itself. + - [Jim] I sometimes wish for more normative, less chatty module documentation. e.g. [*heapq* module](https://docs.python.org/3/library/heapq.html). e.g. old issue 29428 [*Doctest documentation unclear about multi-line fixtures*](https://bugs.python.org/issue29428). + bad example commit messages + - https://devguide.python.org/getting-started/git-boot-camp/#accepting-and-merging-a-pull-request + - [python/devguide#1235](https://github.com/python/devguide/pull/1235) + - Should we do this for PEPs? see [python/docs-community#22](https://github.com/python/docs-community/issues/22) + - [Hugo] See also [python/peps#3567](https://github.com/python/peps/pull/3567) for green/red sidebars for good/bad example code in PEPs + - [Jim] don't forget accessibility constraints when coming up with the style guide. e.g. some readers are red/green colourblind. βœ…βŒ are good in that they are legible even without colour. + +- [Ryan] Thoughts about completing TOML->JSON conversion table: https://docs.python.org/3/library/tomllib.html#conversion-table and the TOML spec: https://toml.io/en/v1.0.0#spec + +- [Jim] FYI, Unicode Standard is changing form of authoritative standard documents from PDF to HTML, with corresponding change to document production tooling. If this is interesting I can provide more info. I am in the working group which is working on the new tooling. + + +## Next meeting + +The docs team generally meets on the first Tuesday of every month around 20:00-ish UTC. + +We have a recurring Google Calendar event for the meeting. +Let Mariatta know your email address and she can invite you. diff --git a/docs/monthly-meeting/index.rst b/docs/monthly-meeting/index.rst index c98d667..5255b9f 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -34,3 +34,4 @@ Monthly reports in reverse chronological order. Oct 2023 <2023-10.md> Nov 2023 <2023-11.md> Dec 2023 <2023-12.md> + Jan 2024 <2024-01.md> From a453002c8566e16416892fcae458e12697b89af0 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Wed, 3 Jan 2024 17:27:45 +0000 Subject: [PATCH 02/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/monthly-meeting/2024-01.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index 4903b2a..ae79de0 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -37,7 +37,7 @@ Please take a second to read through it! > This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We'll read through these at the beginning of the meeting. -* The Steering Council has [accepted](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9?u=hugovk) [PEP 732](https://peps.python.org/pep-0732/) ("The Python Documentation Editorial Board") πŸŽ‰ +* The Steering Council has [accepted](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9?u=hugovk) [PEP 732](https://peps.python.org/pep-0732/) ("The Python Documentation Editorial Board") πŸŽ‰ - [willingc] First meeting will be January 8, 2024. - [Carol] Looing at docs and website from a new user's perspective @@ -53,7 +53,7 @@ Please take a second to read through it! The `tkinter`, `pty`/`termios`, `sqlite3` (maybe more?) use `master/slave` terminology in API and docs. What's the best way to come up with, and switch to, better terms? - Is there an expert* I should talk to? + Is there an expert* I should talk to? - [willingc] Thursday Bram has authored a Responsible Communications book which may have helpful guidelines. Other communities have used `leader/follower`. [Linux PR on the subject](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb) - [Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (willingc: I like the suggestions in this document for different usages.) @@ -102,9 +102,9 @@ Please take a second to read through it! - [Ryan] standard library documentation reference and adding types to it in a structured way. For example, `collections.Counter.most_common` could be written most_common(n: int) -> list[tuple[Any, int]] - + [Petr] ... or `list[tuple[KeyType, int]]`? - + - this has been discussed. There was opposition to adding the types to the stdlib code itself. - [Jim] I sometimes wish for more normative, less chatty module documentation. e.g. [*heapq* module](https://docs.python.org/3/library/heapq.html). e.g. old issue 29428 [*Doctest documentation unclear about multi-line fixtures*](https://bugs.python.org/issue29428). bad example commit messages From 36f6a92d4e4312b858ce25d8e626ac56da894c03 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Thu, 4 Jan 2024 00:47:48 +0530 Subject: [PATCH 03/10] Update 2024-01.md --- docs/monthly-meeting/2024-01.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index ae79de0..51cfc55 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -94,7 +94,6 @@ Please take a second to read through it! - [CAM] The current tutorial targets people who are already familiar with programming languages. Perhaps we should have separate tutorials for complete beginners and people coming from specific languages. - [Daniele] One drawback of the current tutorial is lots of preamble saying why you want to learn Python. But the user is already here, wanting to learn Python. We should start directly with the examples. Also, we don't need to cover the edge cases right after people do something for the first time. Long explanations detract from the tutorial. - [Ezio] It seems that for the tutorial, examples work better than prose, for both new and experienced users. Also, we could have cheatsheets for people coming from other languages. -- [Carol] There's a bigger pressing need for onboarding people from different groups, like people who don't know how to use the command line. ## Follow-ups from previous meeting(s) From f52a581d3feed84276adacf770a19e6cf81ecc9d Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Thu, 4 Jan 2024 02:29:20 +0530 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Ezio Melotti --- docs/monthly-meeting/2024-01.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index 51cfc55..fe48628 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -39,8 +39,8 @@ Please take a second to read through it! * The Steering Council has [accepted](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9?u=hugovk) [PEP 732](https://peps.python.org/pep-0732/) ("The Python Documentation Editorial Board") πŸŽ‰ - - [willingc] First meeting will be January 8, 2024. - - [Carol] Looing at docs and website from a new user's perspective + - [Carol] First meeting will be January 8, 2024. + - [Carol] Looking at docs and website from a new user's perspective - [Hugo] What would be the best way to contact the Board? [Guido] That's already on the agenda. [Carol] For the short term we could use the docs community repo too. * I [Jim] appreciate how considerate this group is. The particular incident motivating my appreciation is that I got mentioned in the minutes of last meeting, and several people took pains to be sure that my name was presented there as I wanted it to be. Thank you. @@ -55,19 +55,19 @@ Please take a second to read through it! Is there an expert* I should talk to? - - [willingc] Thursday Bram has authored a Responsible Communications book which may have helpful guidelines. Other communities have used `leader/follower`. [Linux PR on the subject](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb) - - [Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (willingc: I like the suggestions in this document for different usages.) + - [Carol] Thursday Bram has authored a Responsible Communications book which may have helpful guidelines. Other communities have used `leader/follower`. [Linux PR on the subject](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb) + - [Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (Carol: I like the suggestions in this document for different usages.) - [CAM] Earlier BPO issue: [python/cpython#78786](https://github.com/python/cpython/issues/78786) - To do - - Check and update the dev guide for new docs not to use terms and suggest alternatives + - Check and update the devguide for new docs not to use terms and suggest alternatives - Determine process for future changes of existing terminology - Consider adding a statement to the documentation about existing code - Petr will bounce ideas off Daniele :) - Ryan tried introducing argument lists (like in [sqlite3](https://docs.python.org/3/library/sqlite3.html#sqlite3.connect)) to the collections module, didn't work too well as the functions take one or two args and they're pretty obvious. Petr recommended looking at `subprocess.Popen`. - - [willingc] Ryan, feel free to ping me when you have an example since I'm very familiar with the scientific python docs. + - [Carol] Ryan, feel free to ping me when you have an example since I'm very familiar with the scientific Python docs. - Guido doesn't like forcing people to stick to a template - Daniele mentions there are two kinds of users, one of which -- a forensic analyst -- could need very strictly formatted documentation - [Guido] The bulleted list makes it less likely to fit everything on a screen. Vertical space is a precious resource. @@ -75,7 +75,7 @@ Please take a second to read through it! - [Carol] Areas where users ask for help most should get most attention - [Ezio] There is some value in a consistent format for return values and exceptions; sometimes it's hard to find them currently. Arguments are usually explained well in the description. - [Daniele] It doesn't need to be machine-readable. It should always be maximally human-comfortable. - - [Jim] It sounds like the framing of this discussion is, source text targetting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion? + - [Jim] It sounds like the framing of this discussion is, source text targeting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion? - [Ned] We write docs twice -- once for the docstrings and once in `rst`. That's more work, but it means we can have different strategies for each use case. [Guido] Changing that would involve several PEPs. - [CAM] Sphinx has ways to generate docs for a whole module, or just a single function, from docstrings. But yes, starting to use that would need a PEP. - [CAM] The strategy we took for `sqlite3` was to focus on the functions with most arguments, where the bulleted lists have most benefit, and leave the smaller functions for later, when we have more experience with the approach. From 70b033357436d2de4f213549755929c7fcbdba9c Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Thu, 4 Jan 2024 02:32:31 +0530 Subject: [PATCH 05/10] Update 2024-01.md --- docs/monthly-meeting/2024-01.md | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index fe48628..39e11bb 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -96,28 +96,6 @@ Please take a second to read through it! - [Ezio] It seems that for the tutorial, examples work better than prose, for both new and experienced users. Also, we could have cheatsheets for people coming from other languages. -## Follow-ups from previous meeting(s) - -- [Ryan] standard library documentation reference and adding types to it in a structured way. For example, `collections.Counter.most_common` could be written - - most_common(n: int) -> list[tuple[Any, int]] - - [Petr] ... or `list[tuple[KeyType, int]]`? - - - this has been discussed. There was opposition to adding the types to the stdlib code itself. - - [Jim] I sometimes wish for more normative, less chatty module documentation. e.g. [*heapq* module](https://docs.python.org/3/library/heapq.html). e.g. old issue 29428 [*Doctest documentation unclear about multi-line fixtures*](https://bugs.python.org/issue29428). - bad example commit messages - - https://devguide.python.org/getting-started/git-boot-camp/#accepting-and-merging-a-pull-request - - [python/devguide#1235](https://github.com/python/devguide/pull/1235) - - Should we do this for PEPs? see [python/docs-community#22](https://github.com/python/docs-community/issues/22) - - [Hugo] See also [python/peps#3567](https://github.com/python/peps/pull/3567) for green/red sidebars for good/bad example code in PEPs - - [Jim] don't forget accessibility constraints when coming up with the style guide. e.g. some readers are red/green colourblind. βœ…βŒ are good in that they are legible even without colour. - -- [Ryan] Thoughts about completing TOML->JSON conversion table: https://docs.python.org/3/library/tomllib.html#conversion-table and the TOML spec: https://toml.io/en/v1.0.0#spec - -- [Jim] FYI, Unicode Standard is changing form of authoritative standard documents from PDF to HTML, with corresponding change to document production tooling. If this is interesting I can provide more info. I am in the working group which is working on the new tooling. - - ## Next meeting The docs team generally meets on the first Tuesday of every month around 20:00-ish UTC. From 820704dbda2dc41a87868908e0bd71d7b77974f9 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Thu, 4 Jan 2024 02:36:03 +0530 Subject: [PATCH 06/10] Update 2024-01.md --- docs/monthly-meeting/2024-01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index 39e11bb..d105463 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -94,7 +94,7 @@ Please take a second to read through it! - [CAM] The current tutorial targets people who are already familiar with programming languages. Perhaps we should have separate tutorials for complete beginners and people coming from specific languages. - [Daniele] One drawback of the current tutorial is lots of preamble saying why you want to learn Python. But the user is already here, wanting to learn Python. We should start directly with the examples. Also, we don't need to cover the edge cases right after people do something for the first time. Long explanations detract from the tutorial. - [Ezio] It seems that for the tutorial, examples work better than prose, for both new and experienced users. Also, we could have cheatsheets for people coming from other languages. - +- [Carol] There's a bigger pressing need for onboarding people from different groups, like people who don't know how to use the command line. ## Next meeting From ab5083069155355e31cb07bdc583ffe5c4411322 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Thu, 4 Jan 2024 10:44:55 +0530 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Ege Akman --- docs/monthly-meeting/2024-01.md | 48 +++++++++++++-------------------- 1 file changed, 18 insertions(+), 30 deletions(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index d105463..b7bbb96 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -33,64 +33,52 @@ Please take a second to read through it! ## Reports and celebrations -> 60 second updates on things you have been up to, questions you have, or developments you think people should know about. Please add yourself, and if you do not have an update to share, you can pass. +- The Steering Council has [accepted](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9?u=hugovk) [PEP 732](https://peps.python.org/pep-0732/) ("The Python Documentation Editorial Board") πŸŽ‰ + - [Carol] First meeting will be January 8, 2024. + - [Carol] Looking at docs and website from a new user's perspective + - [Hugo] What would be the best way to contact the Board? [Guido] That's already on the agenda. [Carol] For the short term we could use the docs community repo too. -> This is a place to make announcements (without a need for discussion). This is also a great place to give shout-outs to contributors! We'll read through these at the beginning of the meeting. +- I [Jim] appreciate how considerate this group is. The particular incident motivating my appreciation is that I got mentioned in the minutes of last meeting, and several people took pains to be sure that my name was presented there as I wanted it to be. Thank you. -* The Steering Council has [accepted](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9?u=hugovk) [PEP 732](https://peps.python.org/pep-0732/) ("The Python Documentation Editorial Board") πŸŽ‰ - - - [Carol] First meeting will be January 8, 2024. - - [Carol] Looking at docs and website from a new user's perspective - - [Hugo] What would be the best way to contact the Board? [Guido] That's already on the agenda. [Carol] For the short term we could use the docs community repo too. - -* I [Jim] appreciate how considerate this group is. The particular incident motivating my appreciation is that I got mentioned in the minutes of last meeting, and several people took pains to be sure that my name was presented there as I wanted it to be. Thank you. - -* [Ryan] We made the update to the TOML documentation we talked about on the last call and got my first Python pull request merged! +- [Ryan] We made the update to the TOML documentation we talked about on the last call and got my first Python pull request merged! ## Discussion -- [Petr] Inclusive language - - The `tkinter`, `pty`/`termios`, `sqlite3` (maybe more?) use `master/slave` terminology in API and docs. What's the best way to come up with, and switch to, better terms? - - Is there an expert* I should talk to? - +- [Petr] The `tkinter`, `pty`/`termios`, `sqlite3` (maybe more?) use `master/slave` terminology in API and docs. What's the best way to come up with, and switch to, better terms? Is there an expert I should talk to? - [Carol] Thursday Bram has authored a Responsible Communications book which may have helpful guidelines. Other communities have used `leader/follower`. [Linux PR on the subject](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb) - [Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (Carol: I like the suggestions in this document for different usages.) - [CAM] Earlier BPO issue: [python/cpython#78786](https://github.com/python/cpython/issues/78786) - - - To do - - Check and update the devguide for new docs not to use terms and suggest alternatives - - Determine process for future changes of existing terminology - - Consider adding a statement to the documentation about existing code + - Next steps: + - Check and update the devguide for new docs not to use terms and suggest alternatives + - Determine process for future changes of existing terminology + - Consider adding a statement to the documentation about existing code - Petr will bounce ideas off Daniele :) - -- Ryan tried introducing argument lists (like in [sqlite3](https://docs.python.org/3/library/sqlite3.html#sqlite3.connect)) to the collections module, didn't work too well as the functions take one or two args and they're pretty obvious. Petr recommended looking at `subprocess.Popen`. +- Ryan tried introducing argument lists (like in [sqlite3](https://docs.python.org/3/library/sqlite3.html#sqlite3.connect)) to the collections module, didn't work too well as the functions take one or two arguments and they're pretty obvious. Petr recommended looking at `subprocess.Popen`. - [Carol] Ryan, feel free to ping me when you have an example since I'm very familiar with the scientific Python docs. - Guido doesn't like forcing people to stick to a template - Daniele mentions there are two kinds of users, one of which -- a forensic analyst -- could need very strictly formatted documentation - [Guido] The bulleted list makes it less likely to fit everything on a screen. Vertical space is a precious resource. - [Carol] Doc usage has changed thanks to intellisense, nowadays you get lists of arguments on hovering. - - [Carol] Areas where users ask for help most should get most attention + - [Carol] Areas where users ask for help most should get most attention. - [Ezio] There is some value in a consistent format for return values and exceptions; sometimes it's hard to find them currently. Arguments are usually explained well in the description. - [Daniele] It doesn't need to be machine-readable. It should always be maximally human-comfortable. - [Jim] It sounds like the framing of this discussion is, source text targeting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion? - - [Ned] We write docs twice -- once for the docstrings and once in `rst`. That's more work, but it means we can have different strategies for each use case. [Guido] Changing that would involve several PEPs. + - [Ned] We write docs twice -- once for the docstrings and once in `rst`. That's more work, but it means we can have different strategies for each use case. + - [Guido] Changing that would involve several PEPs. - [CAM] Sphinx has ways to generate docs for a whole module, or just a single function, from docstrings. But yes, starting to use that would need a PEP. - [CAM] The strategy we took for `sqlite3` was to focus on the functions with most arguments, where the bulleted lists have most benefit, and leave the smaller functions for later, when we have more experience with the approach. - [Carol] And we should keep in mind that our perspectives are not necessarily the users' perspective. If we do make major changes we should think about users and we should vet the changes. - Ryan started contributing by trying to get the contract of [`collections.Counter.most_common`](https://docs.python.org/3/library/collections.html#collections.Counter.most_common), and not finding it in the docstring nor in the documentation. - - Carol: If you're coming from the scientific world, where the `?` in IPython gives you the docstring, that is often the first thing you look at. + - [Carol] If you're coming from the scientific world, where the `?` in IPython gives you the docstring, that is often the first thing you look at. - Ryan will take a look at only documenting return type and "raises" in a structured way, leaving parameters in the prose. - Guido warns that `collections.Counter` is not that typical. -- If we have time, would like to hear from Daniele on the [thread he started on the structure of the Python docs](https://discuss.python.org/t/diataxis-and-python-documentation/41836) as to the takeways from that so far and next steps there. - +- If we have time, would like to hear from Daniele on the [thread he started on the structure of the Python docs](https://discuss.python.org/t/diataxis-and-python-documentation/41836) as to the takeaways from that so far and next steps there. - Discussion between Daniele and Ezio on the Python tutorial - [Ezio] The docs for builtin functions doesn't have any examples. Idea: Add a separate page with 1-3 examples for each function. -- [Carol] always goes back to the users and what their pathways and needs are. The tutorial can't fit all users -- absolute beginners, people for whom Python is the first language, people coming from other languages. The current tutorial doesn't work for completely new users. +- [Carol] We should always go back to the users and what their pathways and needs are. The tutorial can't fit all users -- absolute beginners, people for whom Python is the first language, people coming from other languages. The current tutorial doesn't work for completely new users. - [CAM] The current tutorial targets people who are already familiar with programming languages. Perhaps we should have separate tutorials for complete beginners and people coming from specific languages. - [Daniele] One drawback of the current tutorial is lots of preamble saying why you want to learn Python. But the user is already here, wanting to learn Python. We should start directly with the examples. Also, we don't need to cover the edge cases right after people do something for the first time. Long explanations detract from the tutorial. - [Ezio] It seems that for the tutorial, examples work better than prose, for both new and experienced users. Also, we could have cheatsheets for people coming from other languages. From 80c9ae62b332602a9d63f45196b0fb3532f56330 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Fri, 5 Jan 2024 18:12:33 +0530 Subject: [PATCH 08/10] Update 2024-01.md --- docs/monthly-meeting/2024-01.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index b7bbb96..ae11d35 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -46,7 +46,7 @@ Please take a second to read through it! - [Petr] The `tkinter`, `pty`/`termios`, `sqlite3` (maybe more?) use `master/slave` terminology in API and docs. What's the best way to come up with, and switch to, better terms? Is there an expert I should talk to? - [Carol] Thursday Bram has authored a Responsible Communications book which may have helpful guidelines. Other communities have used `leader/follower`. [Linux PR on the subject](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb) - - [Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (Carol: I like the suggestions in this document for different usages.) + - [Hugo] [Some suggestions](https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave) (Carol: I like the suggestions in this document for different usages.) - [CAM] Earlier BPO issue: [python/cpython#78786](https://github.com/python/cpython/issues/78786) - Next steps: - Check and update the devguide for new docs not to use terms and suggest alternatives From 12cd1da7e912740c2758cc38e65b7dd41ad17353 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Fri, 5 Jan 2024 18:14:00 +0530 Subject: [PATCH 09/10] Update docs/monthly-meeting/2024-01.md Co-authored-by: Ned Batchelder --- docs/monthly-meeting/2024-01.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index ae11d35..f294b26 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -66,6 +66,7 @@ Please take a second to read through it! - [Jim] It sounds like the framing of this discussion is, source text targeting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion? - [Ned] We write docs twice -- once for the docstrings and once in `rst`. That's more work, but it means we can have different strategies for each use case. - [Guido] Changing that would involve several PEPs. + - [Ned] Right, I wasn't suggesting we change it, just ensuring everyone knew. - [CAM] Sphinx has ways to generate docs for a whole module, or just a single function, from docstrings. But yes, starting to use that would need a PEP. - [CAM] The strategy we took for `sqlite3` was to focus on the functions with most arguments, where the bulleted lists have most benefit, and leave the smaller functions for later, when we have more experience with the approach. - [Carol] And we should keep in mind that our perspectives are not necessarily the users' perspective. If we do make major changes we should think about users and we should vet the changes. From b76312e65de502a8e8b258cd134ba4bd1bcfda3e Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Sun, 7 Jan 2024 13:53:16 +0530 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Ezio Melotti --- docs/monthly-meeting/2024-01.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/monthly-meeting/2024-01.md b/docs/monthly-meeting/2024-01.md index f294b26..32fe2c8 100644 --- a/docs/monthly-meeting/2024-01.md +++ b/docs/monthly-meeting/2024-01.md @@ -61,7 +61,8 @@ Please take a second to read through it! - [Guido] The bulleted list makes it less likely to fit everything on a screen. Vertical space is a precious resource. - [Carol] Doc usage has changed thanks to intellisense, nowadays you get lists of arguments on hovering. - [Carol] Areas where users ask for help most should get most attention. - - [Ezio] There is some value in a consistent format for return values and exceptions; sometimes it's hard to find them currently. Arguments are usually explained well in the description. + - [Ezio] In addition to arguments, there are also return values and raised exceptions that [can be documented using specific Sphinx *options*](https://www.sphinx-doc.org/en/master/tutorial/describing-code.html#id5). + - [Ezio] Even though there is some value in having a consistent format for all these, I don't think we should use bullet lists for them throughout the docs since arguments are usually already explained well enough in prose (return values and exceptions are sometimes harder to find though). - [Daniele] It doesn't need to be machine-readable. It should always be maximally human-comfortable. - [Jim] It sounds like the framing of this discussion is, source text targeting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion? - [Ned] We write docs twice -- once for the docstrings and once in `rst`. That's more work, but it means we can have different strategies for each use case. @@ -78,11 +79,11 @@ Please take a second to read through it! - If we have time, would like to hear from Daniele on the [thread he started on the structure of the Python docs](https://discuss.python.org/t/diataxis-and-python-documentation/41836) as to the takeaways from that so far and next steps there. - Discussion between Daniele and Ezio on the Python tutorial -- [Ezio] The docs for builtin functions doesn't have any examples. Idea: Add a separate page with 1-3 examples for each function. - [Carol] We should always go back to the users and what their pathways and needs are. The tutorial can't fit all users -- absolute beginners, people for whom Python is the first language, people coming from other languages. The current tutorial doesn't work for completely new users. - [CAM] The current tutorial targets people who are already familiar with programming languages. Perhaps we should have separate tutorials for complete beginners and people coming from specific languages. - [Daniele] One drawback of the current tutorial is lots of preamble saying why you want to learn Python. But the user is already here, wanting to learn Python. We should start directly with the examples. Also, we don't need to cover the edge cases right after people do something for the first time. Long explanations detract from the tutorial. - [Ezio] It seems that for the tutorial, examples work better than prose, for both new and experienced users. Also, we could have cheatsheets for people coming from other languages. +- [Ezio] As an aside, the docs for builtin functions doesn't have many examples. We could add a separate page with 1-3 examples for each function. - [Carol] There's a bigger pressing need for onboarding people from different groups, like people who don't know how to use the command line. ## Next meeting