Skip to content

Commit

Permalink
Apply suggestions from code review
Browse files Browse the repository at this point in the history
Co-authored-by: Ege Akman <[email protected]>
  • Loading branch information
Unique-Usman and egeakman authored Feb 10, 2024
1 parent 3ab37ef commit dc68872
Showing 1 changed file with 8 additions and 11 deletions.
19 changes: 8 additions & 11 deletions docs/monthly-meeting/2024-02.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -64,25 +63,23 @@ 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
[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)
- [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)
Expand Down

0 comments on commit dc68872

Please sign in to comment.