tweak docs IQSS#9887

doc/sphinx-guides/source/api/changelog.rst

@@ -10,7 +10,7 @@ This API changelog is experimental and we would love feedback on its usefulness.
 v6.3
 ----
 
-- **/api/admin/superuser/{identifier}**: The POST endpoint is being deprecated in favor for the PUT, which we can specifically set the superuser status in the body.
+- **/api/admin/superuser/{identifier}**: The POST endpoint that toggles superuser status has been deprecated in favor of a new PUT endpoint that allows you to specify true or false. See :ref:`set-superuser-status`.
 
 v6.2
 ----

doc/sphinx-guides/source/api/native-api.rst

@@ -5415,31 +5415,43 @@ This action changes the identifier of user johnsmith to jsmith.
 Toggle Superuser Status
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Toggles superuser mode on the ``AuthenticatedUser`` whose ``identifier`` (without the ``@`` sign) is passed. ::
+Toggle the superuser status of a user.
 
-    POST http://$SERVER/api/admin/superuser/$identifier
+.. note:: This endpoint is deprecated as explained in :doc:`/api/changelog`. Please use the :ref:`set-superuser-status` endpoint instead.
 
-.. note:: This endpoint is deprecated. Use the set superuser status endpoint instead.
+.. code-block:: bash
+
+  export SERVER_URL=http://localhost:8080
+  export USERNAME=jdoe
+  curl -X POST "$SERVER_URL/api/admin/superuser/$USERNAME"
 
-.. _change-superuser-status:
+The fully expanded example above (without environment variables) looks like this:
+
+.. code-block:: bash
+
+  curl -X POST "http://localhost:8080/api/admin/superuser/jdoe"
+
+.. _set-superuser-status:
 
 Set Superuser Status
 ~~~~~~~~~~~~~~~~~~~~
 
-Specify the superuser status of a user with a boolean value.
+Specify the superuser status of a user with a boolean value (``true`` or ``false``).
+
+.. note:: See :ref:`curl-examples-and-environment-variables` if you are unfamiliar with the use of ``export`` below.
 
 .. code-block:: bash
 
   export SERVER_URL=http://localhost:8080
   export USERNAME=jdoe
   export IS_SUPERUSER=true
-  curl -X PUT "$SERVER/api/admin/superuser/$USERNAME" -d "$IS_SUPERUSER"
+  curl -X PUT "$SERVER_URL/api/admin/superuser/$USERNAME" -d "$IS_SUPERUSER"
 
 The fully expanded example above (without environment variables) looks like this:
 
 .. code-block:: bash
 
-  curl -X PUT "http://localhost:8080/api/admin/superuser/jdoe"  -d "true"
+  curl -X PUT "http://localhost:8080/api/admin/superuser/jdoe" -d true
 
 .. _delete-a-user: