diff --git a/docs/source/upgrade-guide.md b/docs/source/upgrade-guide.md
index 546b31cc9c..8ea4a5f110 100644
--- a/docs/source/upgrade-guide.md
+++ b/docs/source/upgrade-guide.md
@@ -39,22 +39,23 @@ In `plone.restapi` 9.0.0, the following response would be returned with a `breac
 
 Pull Request: https://github.com/plone/plone.restapi/pull/1636
 
-### Remove deprecated @unlock, @refresh-lock endpoints
 
-The deprecated @unlock and @refresh-unlock endpoints were removed in `plone.restapi` 9.
+### Remove deprecated `@unlock`, `@refresh-lock` endpoints
 
-Send a DELETE request to the @lock endpoint to release a lock (replaces the @unlock endpoint).
+The deprecated `@unlock` and `@refresh-unlock` endpoints were removed in `plone.restapi` 9.
 
-Send a PATCH request to the @lock endpoint to refresh a lock (replaces the @refresh-unlock endpoint).
+Send a `DELETE` request to the `@lock` endpoint to release a lock (replaces the `@unlock` endpoint).
+
+Send a `PATCH` request to the `@lock` endpoint to refresh a lock (replaces the `@refresh-unlock` endpoint).
 
 See the documentation of the `@lock`endpoint for more information: https://plonerestapi.readthedocs.io/en/latest/endpoints/locking.html
 
 Pull Request: https://github.com/plone/plone.restapi/pull/1235
 
 
-### Remove plone.tiles and the @tiles endpoint
+### Remove `plone.tiles` and the `@tiles` endpoint
 
-`plone.restapi` 9 removed the @tiles endpoint and removed the dependency to plone.tiles. The @tiles endpoint was deprecated since `plone.restapi` 8.
+`plone.restapi` 9 removed the `@tiles` endpoint and removed the dependency to `plone.tiles`. The `@tiles` endpoint was deprecated since `plone.restapi` 8.
 
 Pull Request: https://github.com/plone/plone.restapi/pull/1688
 
diff --git a/news/1698.documentation b/news/1698.documentation
new file mode 100644
index 0000000000..83ca9c3737
--- /dev/null
+++ b/news/1698.documentation
@@ -0,0 +1 @@
+Polish docs for v9 release. @stevepiercy