Apply suggestions from code review

Co-authored-by: Ezio Melotti <[email protected]>

docs/monthly-meeting/2024-01.md

@@ -61,7 +61,8 @@ Please take a second to read through it!
   - [Guido] The bulleted list makes it less likely to fit everything on a screen. Vertical space is a precious resource.
   - [Carol] Doc usage has changed thanks to intellisense, nowadays you get lists of arguments on hovering.
   - [Carol] Areas where users ask for help most should get most attention.
-  - [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.
+  - [Ezio] In addition to arguments, there are also return values and raised exceptions that [can be documented using specific Sphinx *options*](https://www.sphinx-doc.org/en/master/tutorial/describing-code.html#id5).
+  - [Ezio] Even though there is some value in having a consistent format for all these, I don't think we should use bullet lists for them throughout the docs since arguments are usually already explained well enough in prose (return values and exceptions are sometimes harder to find though).
   - [Daniele] It doesn't need to be machine-readable. It should always be maximally human-comfortable.
   - [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?
   - [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.
@@ -78,11 +79,11 @@ Please take a second to read through it!
 - If we have time, would like to hear from Daniele on the [thread he started on the structure of the Python docs](https://discuss.python.org/t/diataxis-and-python-documentation/41836) as to the takeaways from that so far and next steps there.
   - Discussion between Daniele and Ezio on the Python tutorial
 
-- [Ezio] The docs for builtin functions doesn't have any examples. Idea: Add a separate page with 1-3 examples for each function.
 - [Carol] We should always go back to the users and what their pathways and needs are. The tutorial can't fit all users -- absolute beginners, people for whom Python is the first language, people coming from other languages. The current tutorial doesn't work for completely new users.
 - [CAM] The current tutorial targets people who are already familiar with programming languages. Perhaps we should have separate tutorials for complete beginners and people coming from specific languages.
 - [Daniele] One drawback of the current tutorial is lots of preamble saying why you want to learn Python. But the user is already here, wanting to learn Python. We should start directly with the examples. Also, we don't need to cover the edge cases right after people do something for the first time. Long explanations detract from the tutorial.
 - [Ezio] It seems that for the tutorial, examples work better than prose, for both new and experienced users. Also, we could have cheatsheets for people coming from other languages.
+- [Ezio] As an aside, the docs for builtin functions doesn't have many examples. We could add a separate page with 1-3 examples for each function.
 - [Carol] There's a bigger pressing need for onboarding people from different groups, like people who don't know how to use the command line.
 
 ## Next meeting