Documentation fixes for #1599 (#1692)

* Documentation fixes for #1599

* Add changelog entry

---------

Co-authored-by: Timo Stollenwerk <tisto@users.noreply.github.com>

docs/source/endpoints/users.md

@@ -12,6 +12,7 @@ myst:
 Available users in a Plone site can be created, queried, updated, and deleted by interacting with the `/@users` endpoint on portal root.
 This action requires an authenticated user:
 
+
 ## List Users
 
 To retrieve a list of all current users in the portal, call the `/@users` endpoint with a `GET` request:
@@ -55,6 +56,7 @@ The server will return a {term}`401 Unauthorized` status code.
 :language: http
 ```
 
+
 ### Filtering the list of users
 
 The endpoint supports some basic filtering.
@@ -88,6 +90,7 @@ The server will respond with a list of users where the users are member of one o
 The endpoint also takes a `limit` parameter.
 Its default is a maximum of 25 users at a time for performance reasons.
 
+
 ### Search users
 
 Search by `id`, `fullname` and `email`:
@@ -103,6 +106,7 @@ The server will respond with a list of users where the `fullname`, `email` or `i
 :language: http
 ```
 
+
 ## Create User
 
 To create a new user, send a `POST` request to the global `/@users` endpoint with a JSON representation of the user you want to create in the body:
@@ -129,6 +133,7 @@ The `Location` header contains the URL of the newly created user, and the resour
 
 If no roles have been specified, then a `Member` role is added as a sensible default.
 
+
 ## Read User
 
 To retrieve all details for a particular user, send a `GET` request to the `/@users` endpoint and append the user ID to the URL:
@@ -185,6 +190,7 @@ In this case, the server will respond with a {term}`200 OK` status code and the
 :language: http
 ```
 
+
 ## Update User
 
 To update the settings of a user, send a `PATCH` request with the user details you want to amend to the URL of that particular user.
@@ -229,6 +235,7 @@ If you still want Plone to take care of image scaling using the default Plone be
     :request: ../../../src/plone/restapi/tests/http-examples/users_update_portrait_scale.req
 ```
 
+
 ## Delete User
 
 To delete a user, send a `DELETE` request to the `/@users` endpoint and append the user ID of the user you want to delete.
@@ -245,13 +252,14 @@ A successful response will be indicated by a {term}`204 No Content` response:
 :language: http
 ```
 
-When deleting a user in large sites with a lot of users and content the deleting operation may take a lot of time to the extent of setting it in an unresponsive state.
+When deleting a user in large sites with a lot of users and content, the `delete` operation may take a lot of time to the extent that the site enters an unresponsive state.
 
-There is a workaround about this which is to request Plone not to delete the Member areas or the local roles that may have been granted in the past.
+There is a workaround for this.
+You may request Plone not to delete the member areas or the local roles that may have been granted in the past.
 
-To mark such a behavior we need to pass specific parameters to the delete endpoint.
+To mark such a behavior, we need to pass specific parameters to the `delete` endpoint.
 
-In this case we request not to delete the local roles:
+In this case, we request not to delete the local roles:
 
 ```{eval-rst}
 ..  http:example:: curl httpie python-requests
@@ -282,11 +290,12 @@ Both parameters can be added in the same request.
 ```{warning}
 These two specific requests should be made with special care because they may leave traces of the deleted users in the Plone database.
 
-Specifically, although the user is deleted the reference of its permissions stay on the database.
+Specifically, although the user is deleted, the reference of its permissions stay in the database.
 
-This means that if in the future you add a new user with the same userid, it may get the local roles and member area previously created for the old user.
+This means that if in the future you add a new user with the same `userid`, it may get the local roles and member area previously created for the old user.
 ```
 
+
 ## User registration
 
 Plone allows you to enable user self registration.
@@ -309,6 +318,7 @@ If the user has been created, the server will respond with a {term}`201 Created`
 :language: http
 ```
 
+
 ## Reset User Password
 
 Plone allows to reset a password for a user by sending a `POST` request to the user resource and appending `/reset-password` to the URL:
@@ -328,6 +338,7 @@ The token that is part of the reset URL in the email can be used to authorize se
     :request: ../../../src/plone/restapi/tests/http-examples/users_reset.req
 ```
 
+
 ### Reset Own Password
 
 Plone also allows a user to reset her own password directly without sending an email.
@@ -351,6 +362,7 @@ To set the password with the old password, you need either the `Set own password
 
 If an API consumer tries to send a password in the payload that is not the same as the currently logged in user, the server will respond with a {term}`400 Bad Request` response.
 
+
 ### Return Values
 
 - {term}`200 OK`

news/1692.documentation

@@ -0,0 +1 @@
+Documentation fixes for #1599. @stevepiercy