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-01.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,8 +39,8 @@ Please take a second to read through it!
39
39
40
40
* The Steering Council has [accepted](https://discuss.python.org/t/pep-732-the-python-documentation-editorial-board/36710/9?u=hugovk)[PEP 732](https://peps.python.org/pep-0732/) ("The Python Documentation Editorial Board") 🎉
41
41
42
-
-[willingc] First meeting will be January 8, 2024.
43
-
-[Carol]Looing at docs and website from a new user's perspective
42
+
-[Carol] First meeting will be January 8, 2024.
43
+
-[Carol]Looking at docs and website from a new user's perspective
44
44
-[Hugo] What would be the best way to contact the Board? [Guido] That's already on the agenda. [Carol] For the short term we could use the docs community repo too.
45
45
46
46
* I [Jim] appreciate how considerate this group is. The particular incident motivating my appreciation is that I got mentioned in the minutes of last meeting, and several people took pains to be sure that my name was presented there as I wanted it to be. Thank you.
@@ -55,27 +55,27 @@ Please take a second to read through it!
55
55
56
56
Is there an expert* I should talk to?
57
57
58
-
-[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)
59
-
-[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.)
58
+
-[Carol] 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)
59
+
-[Hugo] Some suggestions: https://www.ietf.org/archive/id/draft-knodel-terminology-14.html#name-master-slave (Carol: I like the suggestions in this document for different usages.)
- Check and update the dev guide for new docs not to use terms and suggest alternatives
63
+
- Check and update the devguide for new docs not to use terms and suggest alternatives
64
64
- Determine process for future changes of existing terminology
65
65
- Consider adding a statement to the documentation about existing code
66
66
- Petr will bounce ideas off Daniele :)
67
67
68
68
69
69
- Ryan tried introducing argument lists (like in [sqlite3](https://docs.python.org/3/library/sqlite3.html#sqlite3.connect)) to the collections module, didn't work too well as the functions take one or two args and they're pretty obvious. Petr recommended looking at `subprocess.Popen`.
70
-
-[willingc] Ryan, feel free to ping me when you have an example since I'm very familiar with the scientific python docs.
70
+
-[Carol] Ryan, feel free to ping me when you have an example since I'm very familiar with the scientific Python docs.
71
71
- Guido doesn't like forcing people to stick to a template
72
72
- Daniele mentions there are two kinds of users, one of which -- a forensic analyst -- could need very strictly formatted documentation
73
73
-[Guido] The bulleted list makes it less likely to fit everything on a screen. Vertical space is a precious resource.
74
74
-[Carol] Doc usage has changed thanks to intellisense, nowadays you get lists of arguments on hovering.
75
75
-[Carol] Areas where users ask for help most should get most attention
76
76
-[Ezio] There is some value in a consistent format for return values and exceptions; sometimes it's hard to find them currently. Arguments are usually explained well in the description.
77
77
-[Daniele] It doesn't need to be machine-readable. It should always be maximally human-comfortable.
78
-
-[Jim] It sounds like the framing of this discussion is, source text targetting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion?
78
+
-[Jim] It sounds like the framing of this discussion is, source text targeting a big module documentation page with docs for all that module's methods. There are other possible targets: docstrings, tooltips text. Are there other targets for doc source which we should consider in this discussion?
79
79
-[Ned] We write docs twice -- once for the docstrings and once in `rst`. That's more work, but it means we can have different strategies for each use case. [Guido] Changing that would involve several PEPs.
80
80
-[CAM] Sphinx has ways to generate docs for a whole module, or just a single function, from docstrings. But yes, starting to use that would need a PEP.
81
81
-[CAM] The strategy we took for `sqlite3` was to focus on the functions with most arguments, where the bulleted lists have most benefit, and leave the smaller functions for later, when we have more experience with the approach.
0 commit comments