You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/monthly-meeting/2024-02.md
+8-11Lines changed: 8 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -44,14 +44,13 @@ Please take a second to read through it!
44
44
45
45
See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662)
46
46
47
-
[Daniele] Examples work best as relief from dense abstract docs.
48
-
They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold.
47
+
[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.
49
48
[Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it.
50
49
[Daniele] An example section sounds like the beginnings of how-to page.
51
50
[Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least insome places.
52
-
[CAM]tutorials vs. how-tos - that depends on the purpose of the examples
53
-
[Ned]how do we turn this thinking into actionable items people can help with?
54
-
[Ezio]we should start adding examples.
51
+
[CAM]Tutorials vs. how-tos - that depends on the purpose of the examples
52
+
[Ned]How do we turn this thinking into actionable items people can help with?
53
+
[Ezio]We should start adding examples.
55
54
56
55
[Ezio] We should also figure out what to do about collapsible sections.
57
56
[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,25 +63,23 @@ Please take a second to read through it!
64
63
[Ned] re. pages being too long, we might switch to having a page for each function
65
64
[Carol] we could run a cron job to count lines
66
65
67
-
-[Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294)
68
-
69
-
Manuel Kaufmann, Ee, Julien were supportive
66
+
-[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)
70
67
71
68
[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.
72
69
73
70
-[Carol] Improving clarity around HOWTO docs: https://github.com/python/cpython/issues/114976
74
71
75
-
[CAM]could you explain what the older-style howtos were?
72
+
[CAM]Could you explain what the older-style howtos were?
76
73
[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
77
-
[Ned] Maybe the section could be called “longer writings”
74
+
[Ned] Maybe the section could be called "longer writings"
78
75
[Daniele] I always call them *howto guides*: `HOWTO` sounds like an old-school passcode
79
76
[Carol] Could we use local ToC trees to split up the section?
80
77
[Hugo] We could fix that quickly if someone wants to make a PR
81
78
[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
82
79
[Carol] The Linux project created both alphabetical and chronological lists of “HOWTO”s. Eventually, we can orphan the current format of the landing page.
83
80
[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.
84
81
85
-
-[Hugo] The detailed changelog is very long -- longer than Moby Dick. [python/docs-community#98](https://github.com/python/docs-community/issues/98)
82
+
-[Hugo] The detailed changelog is very long -- longer than Moby Dick. ([python/docs-community#98](https://github.com/python/docs-community/issues/98))
0 commit comments