DOC: Improve What's new entry description

timhoffm · timhoffm · commit 30db8534e152 · 2025-03-11T00:08:33.000+01:00
diff --git a/doc/api/next_api_changes/README.rst b/doc/api/next_api_changes/README.rst
@@ -39,6 +39,7 @@ A typical entry could look like this::
 
 Please avoid using references in section titles, as it causes links to be
 confusing in the table of contents. Instead, ensure that a reference is
-included in the descriptive text.
+included in the descriptive text. Use inline literals (double backticks)
+to denote code objects in the title.
 
 .. api-change-guide-end
diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
@@ -13,8 +13,8 @@ the API and any changes, either semantic or aesthetic, are backwards-incompatibl
 API changes.
 
 
-Add new API and features
-------------------------
+Add new API
+-----------
 
 Every new function, parameter and attribute that is not explicitly marked as
 private (i.e., starts with an underscore) becomes part of Matplotlib's public
@@ -210,7 +210,8 @@ Announce new and deprecated API
 
 When adding or changing the API in a backward in-compatible way, please add the
 appropriate :ref:`versioning directive <versioning-directives>` and document it
-for the release notes and add the entry to the appropriate folder:
+in the :ref:`release notes <release-notes>` by adding an entry to the appropriate
+folder:
 
 +-------------------+-----------------------------+----------------------------------------------+
 |                   |   versioning directive      |  announcement folder                         |
@@ -278,6 +279,8 @@ For classes and functions, the directive should be placed before the
 end of the parameter description. The micro release version is omitted and
 the directive should not be added to entire modules.
 
+.. _release-notes:
+
 Release notes
 ^^^^^^^^^^^^^
 
diff --git a/doc/devel/pr_guide.rst b/doc/devel/pr_guide.rst
@@ -41,7 +41,7 @@ guidelines before submitting a pull request:
 * For high-level plotting functions, consider adding a small example to the
   :ref:`examples gallery <gallery>`.
 
-* If you add a major new feature or change the API in a backward-incompatible
+* If you add a new feature or change the API in a backward-incompatible
   way, please document it as described in :ref:`api_changes`.
 
 * Code should follow our conventions as documented in our :ref:`coding_guidelines`.
diff --git a/doc/users/next_whats_new/README.rst b/doc/users/next_whats_new/README.rst
@@ -9,11 +9,14 @@
 
 Instructions for writing "What's new" entries
 =============================================
-
 .. whats-new-guide-start
 
-Please place new portions of :file:`whats_new.rst` in the
-:file:`doc/users/next_whats_new/` directory.
+Each new feature (e.g. function, parameter, config value, behavior, ...) must
+be described through a "What's new" entry.
+
+Each entry is written into a separate file in the
+:file:`doc/users/next_whats_new/` directory. They are sorted and merged into
+:file:`whats_new.rst` during the release process.
 
 When adding an entry please look at the currently existing files to
 see if you can extend any of them.  If you create a file, name it
@@ -26,14 +29,19 @@ Include contents of the form::
     Section title for feature
     -------------------------
 
-    A bunch of text about how awesome the new feature is and examples of how
-    to use it.
+    A description of the feature from the user perspective. This should include
+    what the feature allows users to do and how the feature is used. Technical
+    details should be left out when they do not impact usage, for example
+    implementation details.
 
-    A sub-section
-    ~~~~~~~~~~~~~
+    The description may include a a short instructive example, if it helps to
+    understand the feature.
 
 Please avoid using references in section titles, as it causes links to be
 confusing in the table of contents. Instead, ensure that a reference is
-included in the descriptive text.
+included in the descriptive text. Use inline literals (double backticks)
+to denote code objects in the title.
+
+
 
 .. whats-new-guide-end
