diff --git a/README.md b/README.md
index 6b8c0359b..f1b53b573 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,13 @@ which are a native replacement for annotations. As such, this library is
 considered feature complete, and should receive exclusively bugfixes and
 security fixes.
 
+We do not recommend using this library in new projects and encourage authors
+of downstream libraries to offer support for attributes as an alternative to
+Doctrine Annotations.
+
+Have a look at [our blog](https://www.doctrine-project.org/2022/11/04/annotations-to-attributes.html)
+to learn more.
+
 # Doctrine Annotations
 
 [![Build Status](https://github.com/doctrine/annotations/workflows/Continuous%20Integration/badge.svg?label=build)](https://github.com/doctrine/persistence/actions)
diff --git a/docs/en/index.rst b/docs/en/index.rst
index 7caffb50a..ef173ffa9 100644
--- a/docs/en/index.rst
+++ b/docs/en/index.rst
@@ -7,6 +7,13 @@ which are a native replacement for annotations. As such, this library is
 considered feature complete, and should receive exclusively bugfixes and
 security fixes.
 
+We do not recommend using this library in new projects and encourage authors
+of downstream libraries to offer support for attributes as an alternative to
+Doctrine Annotations.
+
+Have a look at [our blog](https://www.doctrine-project.org/2022/11/04/annotations-to-attributes.html)
+to learn more.
+
 Introduction
 ============
 
@@ -38,7 +45,7 @@ You can install the Annotation component with composer:
 
 .. code-block::
 
-    $ composer require doctrine/annotations
+    $ composer require doctrine/annotations
 
 Create an annotation class
 ==========================