bpo-43987: Add "Annotations Best Practices" HOWTO doc. (#25746)

Add "Annotations Best Practices" HOWTO doc.

1 files changed, 6 insertions, 2 deletions

diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
index a59e2e5..679522b 100644
--- a/Doc/whatsnew/3.10.rst
+++ b/Doc/whatsnew/3.10.rst
@@ -807,7 +807,9 @@ Other Language Changes
 
 * Class and module objects now lazy-create empty annotations dicts on demand.
   The annotations dicts are stored in the object’s ``__dict__`` for
-  backwards compatibility.
+  backwards compatibility.  This improves the best practices for working
+  with ``__annotations__``; for more information, please see
+  :ref:`annotations-howto`.
   (Contributed by Larry Hastings in :issue:`43901`.)
 
 New Modules
@@ -996,7 +998,9 @@ defined on an object. It works around the quirks of accessing the annotations
 on various types of objects, and makes very few assumptions about the object
 it examines. :func:`inspect.get_annotations` can also correctly un-stringize
 stringized annotations.  :func:`inspect.get_annotations` is now considered
-best practice for accessing the annotations dict defined on any Python object.
+best practice for accessing the annotations dict defined on any Python object;
+for more information on best practices for working with annotations, please see
+:ref:`annotations-howto`.
 Relatedly, :func:`inspect.signature`,
 :func:`inspect.Signature.from_callable`, and ``inspect.Signature.from_function``
 now call :func:`inspect.get_annotations` to retrieve annotations. This means