Skip to content

Commit dc68872

Browse files
Apply suggestions from code review
Co-authored-by: Ege Akman <[email protected]>
1 parent 3ab37ef commit dc68872

File tree

1 file changed

+8
-11
lines changed

1 file changed

+8
-11
lines changed

docs/monthly-meeting/2024-02.md

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -44,14 +44,13 @@ Please take a second to read through it!
4444
4545
See also [the Discord thread](https://discord.com/channels/935215565872693329/1199481017464008734) and a [related issue](https://github.com/python/cpython/issues/106318#issuecomment-1906642662)
4646

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.
4948
[Ezio] Maybe we should have simple examples inline, and a section with longer examples at the bottom, with links pointing to it.
5049
[Daniele] An example section sounds like the beginnings of how-to page.
5150
[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.
5554

5655
[Ezio] We should also figure out what to do about collapsible sections.
5756
[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!
6463
[Ned] re. pages being too long, we might switch to having a page for each function
6564
[Carol] we could run a cron job to count lines
6665

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)
7067

7168
[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.
7269

7370
- [Carol] Improving clarity around HOWTO docs: https://github.com/python/cpython/issues/114976
7471

75-
[CAM] could you explain what the older-style howtos were?
72+
[CAM] Could you explain what the older-style howtos were?
7673
[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"
7875
[Daniele] I always call them *howto guides*: `HOWTO` sounds like an old-school passcode
7976
[Carol] Could we use local ToC trees to split up the section?
8077
[Hugo] We could fix that quickly if someone wants to make a PR
8178
[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
8279
[Carol] The Linux project created both alphabetical and chronological lists of “HOWTO”s. Eventually, we can orphan the current format of the landing page.
8380
[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.
8481

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))
8683

8784

8885
## Follow-ups from previous meeting(s)

0 commit comments

Comments
 (0)