This RFC concerns new wording for the "Extended summary" and "Notes" content guidelines in DM's Numpydoc style guide.
The issue is that the current wording, coming from the original Numpydoc style guide, seemed to encourage us to put all important conceptual documentation about an API in the extended summary (located right below the summary sentence), and reserve the Notes section only for fairly unimportant implementation details. See the current documentation on Extended Summary and Notes.
The result is that in many docstrings we're writing fairly lengthy and detailed extended summary sections. I'm fairly confident that this isn't the intent of the original numpydoc guidelines, and it certainly isn't what you can see in Numpy, Science, and even Astropy documentation.
The reason that I am invested in ensuring that the extended summary remains a summary (in the sense of brevity) is that long extended summaries impact the usability of our API reference pages (in my opinion). Users, I believe, expect to see the Parameters documentation in close proximity to the API signature at the top of an API reference. It's useful to be able to glance back and forth between the signature and Parameters section to see default values, for example. Now if the extended summary is quite long, it becomes necessary to do a fair amount of scrolling to glance between the signature and the parameters. On the other hand, the Notes section is an ideal place to put the bulk of an API's conceptual documentation. Notes also leads directly into the Examples section.
DM-16826, I have attempted to reword the guidelines for the extended summary and notes section to clarify their usage. This RFC seeks to adopt these new wordings. Draft text:
I propose that this RFC will be implemented by closing
DM-16826. I don't expect us to proactively review and edit all of our docstrings. Rather, I expect us to follow the new guidelines going forward and edit existing docstrings and we encounter them in regular work.