Skip to content

Commit f52a581

Browse files
Apply suggestions from code review
Co-authored-by: Ezio Melotti <[email protected]>
1 parent 36f6a92 commit f52a581

File tree

1 file changed

+7
-7
lines changed

1 file changed

+7
-7
lines changed

docs/monthly-meeting/2024-01.md

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -39,8 +39,8 @@ Please take a second to read through it!
3939
4040
* 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") 🎉
4141

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
4444
- [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.
4545

4646
* 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!
5555

5656
Is there an expert* I should talk to?
5757

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.)
6060
- [CAM] Earlier BPO issue: [python/cpython#78786](https://github.com/python/cpython/issues/78786)
6161

6262
- To do
63-
- 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
6464
- Determine process for future changes of existing terminology
6565
- Consider adding a statement to the documentation about existing code
6666
- Petr will bounce ideas off Daniele :)
6767

6868

6969
- 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.
7171
- Guido doesn't like forcing people to stick to a template
7272
- Daniele mentions there are two kinds of users, one of which -- a forensic analyst -- could need very strictly formatted documentation
7373
- [Guido] The bulleted list makes it less likely to fit everything on a screen. Vertical space is a precious resource.
7474
- [Carol] Doc usage has changed thanks to intellisense, nowadays you get lists of arguments on hovering.
7575
- [Carol] Areas where users ask for help most should get most attention
7676
- [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.
7777
- [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?
7979
- [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.
8080
- [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.
8181
- [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

Comments
 (0)