Skip to content

Commit 53be5d3

Browse files
[pre-commit.ci] auto fixes from pre-commit.com hooks
for more information, see https://pre-commit.ci
1 parent f3bfb59 commit 53be5d3

File tree

1 file changed

+9
-9
lines changed

1 file changed

+9
-9
lines changed

docs/monthly-meeting/2024-02.md

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -45,33 +45,33 @@ Please take a second to read through it!
4545
> [...] **Should we have some convention on where to put examples?**
4646
>
4747
> 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+
5151
[Daniele] Examples work best as relief from dense abstract docs.
5252
They should be boring, and simple. You don't need to be exhaustive; the example is only a handhold.
5353
[Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it.
5454
[Daniele] An example section sounds like the beginnings of how-to page.
5555
[Ned] I like examples for clarifying the text in the reference sections. Interspersing examples into the reference would help, at least insome places.
5656
[CAM] tutorials vs. how-tos - that depends on the purpose of the examples
5757
[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+
6060
[Ezio] We should also figure out what to do about collapsible sections.
6161
[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)
6262
[Ezio] If we agree to add basic examples inline, but bigger examples on the bottom, we won't need collapsible sections.
6363
[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+
6565
[Ezio] Would it make sense to do different things based on the builder, e.g. collapsible sections for HTML and something else for PDF?
6666
[CAM] Yes. Some current directives for collapsible sections do that.
67-
67+
6868
[Ned] re. pages being too long, we might switch to having a page for each function
6969
[Carol] we could run a cron job to count lines
7070

7171
- [Hugo] Hosting docs on Read the Docs [python/docs-community#5 (comment)](https://github.com/python/docs-community/issues/5#issuecomment-1900698294)
7272

7373
Manuel Kaufmann, Ee, Julien were supportive
74-
74+
7575
[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.
7676

7777
- [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!
9898

9999
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?
100100

101-
Is there an expert* I should talk to?
101+
Is there an expert* I should talk to?
102102

103103
- [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)
104104
- [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

Comments
 (0)