From 9e0d69fc78b10564ef631350499b6be90db8eebe Mon Sep 17 00:00:00 2001 From: Unique-Usman Date: Sun, 11 Feb 2024 02:23:43 +0530 Subject: [PATCH 01/10] Add meeting note from Feb 2024 --- docs/monthly-meeting/2024-02.md | 150 ++++++++++++++++++++++++++++++++ docs/monthly-meeting/index.rst | 1 + 2 files changed, 151 insertions(+) create mode 100644 docs/monthly-meeting/2024-02.md diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md new file mode 100644 index 0000000..4b2a646 --- /dev/null +++ b/docs/monthly-meeting/2024-02.md @@ -0,0 +1,150 @@ +# Documentation Community Team Meeting (February 2024) + +- **Date:** 2024-02-06 +- **Time:** [20:00 UTC](https://arewemeetingyet.com/UTC/2024-02-06/20:00/Docs%20Meeting) +- **This HackMD:** https://hackmd.io/@encukou/pydocswg1 +- [**Discourse thread**](https://discuss.python.org/t/44663) (for February) +- [**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]*) +- Hugo van Kemenade / `@hugovk` +- Carol Willing / `@willingc` +- Ezio Melotti / `@ezio-melotti` +- Daniele Procida / `@danieleprocida` +- Ned Batchelder / `@nedbat` +- Marcus Sherman / `@betteridiot` +- Petr Viktorin / `@encukou` +- CAM Gerlach / `@CAM-Gerlach` +- Usman Akinyemi / `@Unique-Usman` + +## 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. + +- [Hugo] 🎉 Since we started fixing the 8,212 Sphinx reference warnings, with 136 PRs + 220 backports we've fixed 56% of them in total (now at 3,574) and 61% of them in `Doc/`. The `.nitignore` initially listed 299 files with warnings; 67% have been fixed, with 100 remaining. 🧹📚 https://discuss.python.org/t/broken-references-in-sphinx-docs/19463/7 + +- [Hugo] Accessibility improvement. Underlining links in recent docs. + +## Discussion + +- [Ezio] Adding examples to the docs, and in particular: + 1. **Should we add more examples in general?** Are they preferable to prose? + 2. Quoting from [this comment](https://github.com/python/cpython/pull/111743#issuecomment-1908471823), especially the last part: + > [...] **Should we have some convention on where to put examples?** + > + > We don't want to end up in a situation where a page uses collapsible sections, another has [examples at the top](https://docs.python.org/3/library/json.html), another [at the bottom](https://docs.python.org/3/library/re.html#regular-expression-examples), another [in the middle](https://docs.python.org/3/library/string.html#format-examples), another [in a separate page](https://docs.python.org/3/howto/logging-cookbook.html), etc. If we agree on some conventions, it will also be easier for users to set their expectations and know where to look. + + See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662) + + [Daniele] Examples work best as relief from dense abstract docs. + They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold. + [Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it. + [Daniele] An example section sounds like the beginnings of how-to page. + [Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least insome places. + [CAM] tutorials vs. how-tos - that depends on the purpose of the examples + [Ned] how do we turn this thinking into actionable items people can help with? + [Ezio] we should start adding examples. + + [Ezio] We should also figure out what to do about collapsible sections. + [Ned] What problem are collapsible sections solving? Do we have too many examples that users will want to ignore? (In my docs I use tabs, but not colapsible sections) + [Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections. + [Carol] So: yes examples, yes inline. We can pause discussions about collapsible sections; if the examples get too long we should think about spinning them out into their own howto pages. **Consensus Recap** + + [Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF? + [CAM] Yes. Some current directives for collapsible sections do that. + + [Ned] re. pages being too long, we might switch to having a page for each function + [Carol] we could run a cron job to count lines + +- [Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294) + + Manuel Kaufmann, Ee, Julien were supportive + + [Hugo] To begin with we could only put HTML there. The only thing we'd need is to redo the version switcher. On RTD they have the fly-out switcher menu, maybe that could be re-styled; Manuel seemed keen to work on that. + +- [Carol] Improving clarity around HOWTO docs: https://github.com/python/cpython/issues/114976 + + [CAM] could you explain what the older-style howtos were? + [Carol] It goes back to Linux in the early days, when docs were scarce. Howtos were architecture discussions of how sonething was implemented, more like background on a topic -- explanations in Diátaxis terms + [Ned] Maybe the section could be called “longer writings” + [Daniele] I always call them *howto guides*: `HOWTO` sounds like an old-school passcode + [Carol] Could we use local ToC trees to split up the section? + [Hugo] We could fix that quickly if someone wants to make a PR + [Ezio] I think there was a discussion, will try to find it later. I was looking at the Unicode guide, which starts out as explanation but then turns into a howto guide, and sometimes it feels like a tutorial. There's an [issue about rewriting it](https://github.com/python/cpython/issues/107583), but I'm not sure how to do that + [Carol] The Linux project created both alphabetical and chronological lists of “HOWTO”s. Eventually, we can orphan the current format of the landing page. + [Carol] One of the urgent tasks is to set the reader's expectations. We don't want them to expect a modern howto and then not get it. + +- [Hugo] The detailed changelog is very long -- longer than Moby Dick. [python/docs-community#98](https://github.com/python/docs-community/issues/98) + + +## Follow-ups from previous meeting(s) + +### January + + +- [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. + + +## 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 5255b9f..3c91fb3 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -35,3 +35,4 @@ Monthly reports in reverse chronological order. Nov 2023 <2023-11.md> Dec 2023 <2023-12.md> Jan 2024 <2024-01.md> + Feb 2024 <2024-02.md> From 53be5d383a2451c4d473baaf6d782ca9732a6e67 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 10 Feb 2024 20:59:18 +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-02.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index 4b2a646..8317ec9 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -45,9 +45,9 @@ Please take a second to read through it! > [...] **Should we have some convention on where to put examples?** > > We don't want to end up in a situation where a page uses collapsible sections, another has [examples at the top](https://docs.python.org/3/library/json.html), another [at the bottom](https://docs.python.org/3/library/re.html#regular-expression-examples), another [in the middle](https://docs.python.org/3/library/string.html#format-examples), another [in a separate page](https://docs.python.org/3/howto/logging-cookbook.html), etc. If we agree on some conventions, it will also be easier for users to set their expectations and know where to look. - - See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662) - + + See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662) + [Daniele] Examples work best as relief from dense abstract docs. They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold. [Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it. @@ -55,23 +55,23 @@ Please take a second to read through it! [Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least insome places. [CAM] tutorials vs. how-tos - that depends on the purpose of the examples [Ned] how do we turn this thinking into actionable items people can help with? - [Ezio] we should start adding examples. - + [Ezio] we should start adding examples. + [Ezio] We should also figure out what to do about collapsible sections. [Ned] What problem are collapsible sections solving? Do we have too many examples that users will want to ignore? (In my docs I use tabs, but not colapsible sections) [Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections. [Carol] So: yes examples, yes inline. We can pause discussions about collapsible sections; if the examples get too long we should think about spinning them out into their own howto pages. **Consensus Recap** - + [Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF? [CAM] Yes. Some current directives for collapsible sections do that. - + [Ned] re. pages being too long, we might switch to having a page for each function [Carol] we could run a cron job to count lines - [Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294) Manuel Kaufmann, Ee, Julien were supportive - + [Hugo] To begin with we could only put HTML there. The only thing we'd need is to redo the version switcher. On RTD they have the fly-out switcher menu, maybe that could be re-styled; Manuel seemed keen to work on that. - [Carol] Improving clarity around HOWTO docs: https://github.com/python/cpython/issues/114976 @@ -98,7 +98,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.) From 3ab37ef8737ec09217de9d153971c6e8fd7fd901 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Sun, 11 Feb 2024 04:11:07 +0530 Subject: [PATCH 03/10] Update docs/monthly-meeting/2024-02.md Co-authored-by: Ege Akman --- docs/monthly-meeting/2024-02.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index 8317ec9..99a0cd0 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -29,10 +29,6 @@ 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. - -> 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. - - [Hugo] 🎉 Since we started fixing the 8,212 Sphinx reference warnings, with 136 PRs + 220 backports we've fixed 56% of them in total (now at 3,574) and 61% of them in `Doc/`. The `.nitignore` initially listed 299 files with warnings; 67% have been fixed, with 100 remaining. 🧹📚 https://discuss.python.org/t/broken-references-in-sphinx-docs/19463/7 - [Hugo] Accessibility improvement. Underlining links in recent docs. From dc68872ffa73b9a52ed2826734f33fe69092904b Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Sun, 11 Feb 2024 04:12:05 +0530 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Ege Akman --- docs/monthly-meeting/2024-02.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index 99a0cd0..f4c5aaf 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -44,14 +44,13 @@ Please take a second to read through it! See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662) - [Daniele] Examples work best as relief from dense abstract docs. - They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold. + [Daniele] Examples work best as relief from dense abstract docs. They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold. [Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it. [Daniele] An example section sounds like the beginnings of how-to page. [Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least insome places. - [CAM] tutorials vs. how-tos - that depends on the purpose of the examples - [Ned] how do we turn this thinking into actionable items people can help with? - [Ezio] we should start adding examples. + [CAM] Tutorials vs. how-tos - that depends on the purpose of the examples + [Ned] How do we turn this thinking into actionable items people can help with? + [Ezio] We should start adding examples. [Ezio] We should also figure out what to do about collapsible sections. [Ned] What problem are collapsible sections solving? Do we have too many examples that users will want to ignore? (In my docs I use tabs, but not colapsible sections) @@ -64,17 +63,15 @@ Please take a second to read through it! [Ned] re. pages being too long, we might switch to having a page for each function [Carol] we could run a cron job to count lines -- [Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294) - - Manuel Kaufmann, Ee, Julien were supportive +- [Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294) (Manuel Kaufmann, Ee, Julien were supportive) [Hugo] To begin with we could only put HTML there. The only thing we'd need is to redo the version switcher. On RTD they have the fly-out switcher menu, maybe that could be re-styled; Manuel seemed keen to work on that. - [Carol] Improving clarity around HOWTO docs: https://github.com/python/cpython/issues/114976 - [CAM] could you explain what the older-style howtos were? + [CAM] Could you explain what the older-style howtos were? [Carol] It goes back to Linux in the early days, when docs were scarce. Howtos were architecture discussions of how sonething was implemented, more like background on a topic -- explanations in Diátaxis terms - [Ned] Maybe the section could be called “longer writings” + [Ned] Maybe the section could be called "longer writings" [Daniele] I always call them *howto guides*: `HOWTO` sounds like an old-school passcode [Carol] Could we use local ToC trees to split up the section? [Hugo] We could fix that quickly if someone wants to make a PR @@ -82,7 +79,7 @@ Please take a second to read through it! [Carol] The Linux project created both alphabetical and chronological lists of “HOWTO”s. Eventually, we can orphan the current format of the landing page. [Carol] One of the urgent tasks is to set the reader's expectations. We don't want them to expect a modern howto and then not get it. -- [Hugo] The detailed changelog is very long -- longer than Moby Dick. [python/docs-community#98](https://github.com/python/docs-community/issues/98) +- [Hugo] The detailed changelog is very long -- longer than Moby Dick. ([python/docs-community#98](https://github.com/python/docs-community/issues/98)) ## Follow-ups from previous meeting(s) From ab631d5db90934d6ded4ccd810f42b2c94e623c7 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Sun, 11 Feb 2024 09:54:41 +0530 Subject: [PATCH 05/10] Update docs/monthly-meeting/2024-02.md Co-authored-by: Ege Akman --- docs/monthly-meeting/2024-02.md | 53 --------------------------------- 1 file changed, 53 deletions(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index f4c5aaf..4a43598 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -82,59 +82,6 @@ Please take a second to read through it! - [Hugo] The detailed changelog is very long -- longer than Moby Dick. ([python/docs-community#98](https://github.com/python/docs-community/issues/98)) -## Follow-ups from previous meeting(s) - -### January - - -- [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. - - ## Next meeting The docs team generally meets on the first Tuesday of every month around 20:00-ish UTC. From 9f08369dda190310430ca95f0008444ad99442f4 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Mon, 12 Feb 2024 17:49:44 +0530 Subject: [PATCH 06/10] Apply suggestions from code review Co-authored-by: Ezio Melotti --- docs/monthly-meeting/2024-02.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index 4a43598..c7597a8 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -53,10 +53,11 @@ Please take a second to read through it! [Ezio] We should start adding examples. [Ezio] We should also figure out what to do about collapsible sections. - [Ned] What problem are collapsible sections solving? Do we have too many examples that users will want to ignore? (In my docs I use tabs, but not colapsible sections) + [Ned] What problem are collapsible sections solving? Do we have too many examples that users will want to ignore? (In my docs I use tabs, but not collapsible sections) [Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections. [Carol] So: yes examples, yes inline. We can pause discussions about collapsible sections; if the examples get too long we should think about spinning them out into their own howto pages. **Consensus Recap** - + [Ezio] We could create a custom Sphinx directive that creates a link to the "Examples" section too. It should be unobtrusive and recognizable (it could have an icon, and a short text like "See more examples."). + [Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF? [CAM] Yes. Some current directives for collapsible sections do that. @@ -75,11 +76,12 @@ Please take a second to read through it! [Daniele] I always call them *howto guides*: `HOWTO` sounds like an old-school passcode [Carol] Could we use local ToC trees to split up the section? [Hugo] We could fix that quickly if someone wants to make a PR - [Ezio] I think there was a discussion, will try to find it later. I was looking at the Unicode guide, which starts out as explanation but then turns into a howto guide, and sometimes it feels like a tutorial. There's an [issue about rewriting it](https://github.com/python/cpython/issues/107583), but I'm not sure how to do that + [Ezio] I was looking at the Unicode guide, which starts out as explanation but then turns into a howto guide, and sometimes it feels like a tutorial. There's an [issue about rewriting it](https://github.com/python/cpython/issues/107583), but I'm not sure what would be the best way to rewrite/reorganize it. [Carol] The Linux project created both alphabetical and chronological lists of “HOWTO”s. Eventually, we can orphan the current format of the landing page. [Carol] One of the urgent tasks is to set the reader's expectations. We don't want them to expect a modern howto and then not get it. - [Hugo] The detailed changelog is very long -- longer than Moby Dick. ([python/docs-community#98](https://github.com/python/docs-community/issues/98)) + [Ezio] Long ago I added an inputbox to filter entries, but [it appears to be broken now](https://github.com/python/cpython/issues/115317). This doesn't make the source page any shorter though. ## Next meeting From c0b9c2b5f3a48e16f02c9035d6fc11e3ca5d9ebf Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 12 Feb 2024 12:22:15 +0000 Subject: [PATCH 07/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/monthly-meeting/2024-02.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index c7597a8..1627341 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -57,7 +57,7 @@ Please take a second to read through it! [Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections. [Carol] So: yes examples, yes inline. We can pause discussions about collapsible sections; if the examples get too long we should think about spinning them out into their own howto pages. **Consensus Recap** [Ezio] We could create a custom Sphinx directive that creates a link to the "Examples" section too. It should be unobtrusive and recognizable (it could have an icon, and a short text like "See more examples."). - + [Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF? [CAM] Yes. Some current directives for collapsible sections do that. From f4da79ccf59c1d292189689e6e9ea1883f4db1ae Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Mon, 12 Feb 2024 18:51:06 +0530 Subject: [PATCH 08/10] Update docs/monthly-meeting/2024-02.md Co-authored-by: Ezio Melotti --- docs/monthly-meeting/2024-02.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index 1627341..e766e6a 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -47,7 +47,7 @@ Please take a second to read through it! [Daniele] Examples work best as relief from dense abstract docs. They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold. [Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it. [Daniele] An example section sounds like the beginnings of how-to page. - [Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least insome places. + [Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least in some places. [CAM] Tutorials vs. how-tos - that depends on the purpose of the examples [Ned] How do we turn this thinking into actionable items people can help with? [Ezio] We should start adding examples. From fb01034f2e2e7b16ab6539438bc53f4f31101a19 Mon Sep 17 00:00:00 2001 From: Unique-Usman <86585626+Unique-Usman@users.noreply.github.com> Date: Fri, 16 Feb 2024 10:56:00 +0530 Subject: [PATCH 09/10] Update docs/monthly-meeting/2024-02.md Co-authored-by: Ezio Melotti --- docs/monthly-meeting/2024-02.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index e766e6a..5a794a4 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -54,15 +54,19 @@ Please take a second to read through it! [Ezio] We should also figure out what to do about collapsible sections. [Ned] What problem are collapsible sections solving? Do we have too many examples that users will want to ignore? (In my docs I use tabs, but not collapsible sections) - [Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections. - [Carol] So: yes examples, yes inline. We can pause discussions about collapsible sections; if the examples get too long we should think about spinning them out into their own howto pages. **Consensus Recap** - [Ezio] We could create a custom Sphinx directive that creates a link to the "Examples" section too. It should be unobtrusive and recognizable (it could have an icon, and a short text like "See more examples."). - - [Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF? - [CAM] Yes. Some current directives for collapsible sections do that. + [Ezio] They allow us to to add more examples inline without making the page too long and more difficult to navigate, but they don't work with non-HTML builders. [Ned] re. pages being too long, we might switch to having a page for each function [Carol] we could run a cron job to count lines + [Ezio] if we count code lines we can determine pages with not enough and too many examples + + [Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF? + [CAM] Yes. Some current directives for collapsible sections do that. + + [Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections. + + [Carol] So: yes examples, yes inline. We can pause discussions about collapsible sections; if the examples get too long we should think about spinning them out into their own howto pages. **Consensus Recap** + [Ezio] We could also create a custom Sphinx directive that creates a link to the "Examples" section. It should be unobtrusive and recognizable (it could have an icon, and a short text like "See more examples."). - [Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294) (Manuel Kaufmann, Ee, Julien were supportive) From e36c7d44d96ed05fe93a8bf42d62831256f4613e Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 16 Feb 2024 05:26:05 +0000 Subject: [PATCH 10/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/monthly-meeting/2024-02.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md index 5a794a4..7e5d6dc 100644 --- a/docs/monthly-meeting/2024-02.md +++ b/docs/monthly-meeting/2024-02.md @@ -62,9 +62,9 @@ Please take a second to read through it! [Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF? [CAM] Yes. Some current directives for collapsible sections do that. - + [Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections. - + [Carol] So: yes examples, yes inline. We can pause discussions about collapsible sections; if the examples get too long we should think about spinning them out into their own howto pages. **Consensus Recap** [Ezio] We could also create a custom Sphinx directive that creates a link to the "Examples" section. It should be unobtrusive and recognizable (it could have an icon, and a short text like "See more examples.").