Merge pull request #106 from Unique-Usman/usma

Add meeting note from Feb 2024

Author: willingc

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.

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>