Polish up Zope manager users

Author: stevepiercy

docs/admin-guide/zope-manager-users.md

@@ -11,96 +11,99 @@ myst:
 
 # Zope manager users
 
-Zope manager users have full access to the whole Zope instance.
+This guide explains how to add a Zope user with the "manager" role—called a "Zope manager user"—to an existing Zope instance.
 
-Some installation methods automatically create a zope `admin` user for you already.
+Zope manager users have full access to the whole Zope instance.
 
-This guide explains how to add a Zope manager user to an existing Zope instance.
+Some installation methods automatically create a Zope manager user named `admin` for you already.
 
-There are multiple reasons why you might need to do that, such as:
+There are multiple reasons why you might need to add a Zope manager user, including the following.
 
 - Your installation method did not create one.
 - You lost access to your instance.
 - You inherited a project without proper documentation.
 
 ```{note}
-If you need to regain access to your instance, this user is also referred to as an **emergency user**.
-```
+If you need to regain access to your instance, this user is also referred to as an "emergency user" in this context only.
 
-```{note}
 The emergency user is a superuser with full access to the Zope instance.
 It is not limited to a specific Plone site.
 Please be aware of the security implications.
-You might want to change the passwords of the already existing manager users after you regained to your instance.
+Consider changing the passwords of the existing Zope manager users after you regain access to your instance.
 ```
 
-(admin-guide-adding-a-new-zope-manager-user-label)=
+(admin-guide-add-a-new-zope-manager-user-label)=
 
 ## Add a new Zope manager user
 
-There are multiple ways to create a Zope manager user.
-That depends on how you created and managed your Zope instance.
+There are multiple methods to create a Zope manager user.
+The method depends on how you created and manage your Zope instance, either via {term}`buildout` or {term}`pip`.
 
 ```{important}
-If you are running a standalone instance, it must be stopped before adding the user.
+If you are running a standalone instance, you must stop it before adding the user.
 ```
 
-(admin-guide-using-the-adduser-instance-command-label)=
+(admin-guide-adduser-instance-command-label)=
 
-### Using the `adduser` instance command
+### `adduser` instance command
 
-If your site was installed with `buildout` and `plone.recipe.zope2instance`, you can add a Zope manager user via an instance script.
+If your site was installed with `buildout` and `plone.recipe.zope2instance`, you can add a Zope manager user via the instance script.
 
-Run the following command in the terminal:
+Run the following command.
 
-```bash
-$ bin/instance adduser username password
-Created user: username
+```shell
+bin/instance adduser username password
 ```
 
 The name of the instance script might vary based on your installation.
 Replace `username` and `password` with the desired values.
 
-If the user already exists:
+If the command is successful, then it will return the following console output.
 
-- No user will be created
-- The password will not be changed
+```console
+Created user: username
+```
 
-The command will return a message like this:
+When you run the script, if the user already exists:
 
-```bash
-$ bin/instance adduser foo baz
-Created user: None
-```
+-   No user will be created.
+-   The password will not be changed. 
+-   The command will return a message such as the following.
 
-(admin-guide-using-the-addzopeuser-command-label)=
+    ```console
+    Created user: None
+    ```
 
-### Using the `addzopeuser` command
+(admin-guide-addzopeuser-command-label)=
 
-For `pip` based installations, you will have a script called `addzopeuser` in the `bin` directory of your virtual environment.
+### `addzopeuser` script
 
+For `pip` based installations, you will have a script called `addzopeuser` in the {file}`bin` directory of your virtual environment.
 The `addzopeuser` script might also be available in `buildout` based installations.
 
-Run in the terminal:
+Run the following command.
 
-```bash
+```shell
 $ .venv/bin/addzopeuser -c path/to/etc/zope.conf username password
-User username created.
 ```
 
-The `addzopeuser` script and `zope.conf` locations might vary based on your installations.
+The `addzopeuser` script and {file}`zope.conf` locations might vary based on your installation.
 Replace `username` and `password` with the desired values.
 
-If the user already exists:
+If the command is successful, then it will return the following console output.
+
+```console
+User username created.
+```
 
-- No user will be created
-- The password will not be changed
+When you run the script, if the user already exists:
 
-The command will return a message like this:
+-   No user will be created.
+-   The password will not be changed.
+-   The command will return a message such as the following.
 
-```bash
-$ .venv/bin/addzopeuser -c tmp/zeoclient/etc/zope.conf foo baz
-Got no result back. User creation may have failed.
-Maybe the user already exists and nothing is done then.
-Or the implementation does not give info when it succeeds.
-```
+    ```console
+    Got no result back. User creation may have failed.
+    Maybe the user already exists and nothing is done then.
+    Or the implementation does not give info when it succeeds.
+    ```