DOC: Improve What's new entry description

Author: timhoffm

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

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,21 @@ 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 features allows them to do and how they can use it. Technical
+    details should be left out if they are not relevant to the user.
+
+    The description may include a a short instructive example, if it helps to
+    understand the feature.
 
-    A sub-section
-    ~~~~~~~~~~~~~
+    Optional sub-section
+    ~~~~~~~~~~~~~~~~~~~~
+    Typical whats-new entries are a single section, but you may add subsections
+    if it makes sense.
 
 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