diff --git a/docs/monthly-meeting/2024-02.md b/docs/monthly-meeting/2024-02.md new file mode 100644 index 0000000..7e5d6dc --- /dev/null +++ b/docs/monthly-meeting/2024-02.md @@ -0,0 +1,96 @@ +# 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 + +- [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 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. + + [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] 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) + + [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 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 + +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 c2d423d..03f8813 100644 --- a/docs/monthly-meeting/index.rst +++ b/docs/monthly-meeting/index.rst @@ -35,3 +35,4 @@ Monthly reports in chronological order. Nov 2023 <2023-11.md> Dec 2023 <2023-12.md> Jan 2024 <2024-01.md> + Feb 2024 <2024-02.md>