diff --git a/docs/topics/documenting-your-api.md b/docs/topics/documenting-your-api.md
index edb989290d..f4fee104bc 100644
--- a/docs/topics/documenting-your-api.md
+++ b/docs/topics/documenting-your-api.md
@@ -4,10 +4,11 @@
 >
 > — Roy Fielding, [REST APIs must be hypertext driven][cite]
 
-REST framework provides a range of different choices for documenting your API. The following
-is a non-exhaustive list of the most popular ones.
+REST framework provides a range of different choices for documenting your API. The following is a non-exhaustive list of some of the most popular options.
 
-## Third party packages for OpenAPI support
+## Third-party packages for OpenAPI support
+
+REST framework recommends using third-party packages for generating and presenting OpenAPI schemas, as they provide more features and flexibility than the built-in (deprecated) implementation.
 
 ### drf-spectacular
 
@@ -37,9 +38,9 @@ This also translates into a very useful interactive documentation viewer in the
 
 ## Built-in OpenAPI schema generation (deprecated)
 
-**Deprecation notice: REST framework's built-in support for generating OpenAPI schemas is
-deprecated in favor of 3rd party packages that can provide this functionality instead.
-As replacement, we recommend using the [drf-spectacular](#drf-spectacular) package.**
+!!! warning
+    **Deprecation notice:** REST framework's built-in support for generating OpenAPI schemas is deprecated in favor of third-party packages that provide this functionality instead. As a replacement, we recommend using **drf-spectacular**.
+
 
 There are a number of packages available that allow you to generate HTML
 documentation pages from OpenAPI schemas.