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
+9-9Lines changed: 9 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -45,33 +45,33 @@ Please take a second to read through it!
45
45
> [...]**Should we have some convention on where to put examples?**
46
46
>
47
47
> 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.
48
-
49
-
See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662)
50
-
48
+
49
+
See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662)
50
+
51
51
[Daniele] Examples work best as relief from dense abstract docs.
52
52
They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold.
53
53
[Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it.
54
54
[Daniele] An example section sounds like the beginnings of how-to page.
55
55
[Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least insome places.
56
56
[CAM] tutorials vs. how-tos - that depends on the purpose of the examples
57
57
[Ned] how do we turn this thinking into actionable items people can help with?
58
-
[Ezio] we should start adding examples.
59
-
58
+
[Ezio] we should start adding examples.
59
+
60
60
[Ezio] We should also figure out what to do about collapsible sections.
61
61
[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)
62
62
[Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections.
63
63
[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**
64
-
64
+
65
65
[Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF?
66
66
[CAM] Yes. Some current directives for collapsible sections do that.
67
-
67
+
68
68
[Ned] re. pages being too long, we might switch to having a page for each function
69
69
[Carol] we could run a cron job to count lines
70
70
71
71
-[Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294)
72
72
73
73
Manuel Kaufmann, Ee, Julien were supportive
74
-
74
+
75
75
[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.
76
76
77
77
-[Carol] Improving clarity around HOWTO docs: https://github.com/python/cpython/issues/114976
@@ -98,7 +98,7 @@ Please take a second to read through it!
98
98
99
99
The `tkinter`, `pty`/`termios`, `sqlite3` (maybe more?) use `master/slave` terminology in API and docs. What's the best way to come up with, and switch to, better terms?
100
100
101
-
Is there an expert* I should talk to?
101
+
Is there an expert* I should talk to?
102
102
103
103
-[willingc] Thursday Bram has authored a Responsible Communications book which may have helpful guidelines. Other communities have used `leader/follower`. [Linux PR on the subject](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=49decddd39e5f6132ccd7d9fdc3d7c470b0061bb)
104
104
-[Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (willingc: I like the suggestions in this document for different usages.)
0 commit comments