Documentation Community Team Meeting (February 2024)#
Date: 2024-02-06
Time: 20:00 UTC
This HackMD: https://hackmd.io/@encukou/pydocswg1
Discourse thread (for February)
Meeting reports (the latest one might be an unmerged PR)
Calendar event: (send your e-mail to Mariatta for an invitation)
How to participate:
Go to Google Meet and ask to be let in.
To edit notes, click the “pencil” or “split view” button on the HackMD document. 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. Please take a second to read through it!
Roll call#
(Name / @GitHubUsername [/ Discord, if different])
Hugo van Kemenade /
@hugovkCarol Willing /
@willingcEzio Melotti /
@ezio-melottiDaniele Procida /
@danieleprocidaNed Batchelder /
@nedbatMarcus Sherman /
@betteridiotPetr Viktorin /
@encukouCAM Gerlach /
@CAM-GerlachUsman 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.nitignoreinitially 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:
Should we add more examples in general? Are they preferable to prose?
Quoting from this comment, 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, another at the bottom, another in the middle, another in a separate page, 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 and a related issue
[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) (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:
HOWTOsounds 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, 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) [Ezio] Long ago I added an inputbox to filter entries, but it appears to be broken now. 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.