From caf225166725d7ccff1fd66cd5cbe679df3d48a6 Mon Sep 17 00:00:00 2001
From: 1letter <1letter@gmx.de>
Date: Thu, 12 Sep 2024 20:57:38 +0200
Subject: [PATCH 01/10] add notes to create an emergency user

---
 docs/backend/index.md                       |  2 +-
 docs/backend/users-groups.md                | 13 -------
 docs/backend/users-groups/emergency-user.md | 40 +++++++++++++++++++++
 docs/backend/users-groups/index.md          | 20 +++++++++++
 4 files changed, 61 insertions(+), 14 deletions(-)
 delete mode 100644 docs/backend/users-groups.md
 create mode 100644 docs/backend/users-groups/emergency-user.md
 create mode 100644 docs/backend/users-groups/index.md

diff --git a/docs/backend/index.md b/docs/backend/index.md
index 3e7dd3278..6420b3437 100644
--- a/docs/backend/index.md
+++ b/docs/backend/index.md
@@ -35,7 +35,7 @@ security
 sending-email
 subscribers
 traversal-acquisition
-users-groups
+users-groups/index
 vocabularies
 widgets
 workflows
diff --git a/docs/backend/users-groups.md b/docs/backend/users-groups.md
deleted file mode 100644
index 9954103d1..000000000
--- a/docs/backend/users-groups.md
+++ /dev/null
@@ -1,13 +0,0 @@
----
-myst:
-  html_meta:
-    "description": ""
-    "property=og:description": ""
-    "property=og:title": ""
-    "keywords": ""
----
-
-(backend-users-groups-label)=
-
-# Users and Groups
-
diff --git a/docs/backend/users-groups/emergency-user.md b/docs/backend/users-groups/emergency-user.md
new file mode 100644
index 000000000..d05e9ab1a
--- /dev/null
+++ b/docs/backend/users-groups/emergency-user.md
@@ -0,0 +1,40 @@
+---
+myst:
+  html_meta:
+    "description": "Create an emergency user"
+    "property=og:description": "Create an emergency user"
+    "property=og:title": "Create an emergency user"
+    "keywords": "Plone, user and groups, emergency user, pip, buildout"
+---
+
+
+(user-groups-emergency-user-label)=
+
+# Emergency user
+
+sometimes it is needed to create an emergency user. the password of admin ist lost or you have inherit a project without a proper documentation. The usecase: you will login as admin to your, but you can't.
+
+First of all, do the following steps not in a production environment! Shutdown your instance.
+
+(user-groups-emergency-user-pip-installation-label)=
+
+## Create an emergency user in a pip based Plone instance
+
+```bash
+./venv/bin/addzopeuser -c instance/etc/zope.conf <user> <password>
+```
+
+start your instance and login with the created user.
+
+(user-groups-emergency-user-buildout-installation-label)=
+
+## Create an emergency user in a buildout based Plone instance
+
+With buildout and plone.recipe.zope2instance you can do
+
+```bash
+bin/instance adduser <user> <password>
+```
+
+start your instance and login with the created user.
+
diff --git a/docs/backend/users-groups/index.md b/docs/backend/users-groups/index.md
new file mode 100644
index 000000000..23c91c3fd
--- /dev/null
+++ b/docs/backend/users-groups/index.md
@@ -0,0 +1,20 @@
+---
+myst:
+  html_meta:
+    "description": "Managing Users And Groups in Plone"
+    "property=og:description": "Managing Users And Groups in Plone"
+    "property=og:title": "Managing Users And Groups in Plone"
+    "keywords": "user, groups, plone"
+---
+
+(backend-users-groups-label)=
+
+# Users and Groups
+
+
+```{toctree}
+:caption: Users and Groups
+:maxdepth: 2
+
+emergency-user
+```
\ No newline at end of file

From b4273e2a46b632cd52abf1cadc1012a792ed4526 Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 13 Sep 2024 02:44:58 -0700
Subject: [PATCH 02/10] Sentence-case index.md

---
 docs/backend/users-groups/index.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/backend/users-groups/index.md b/docs/backend/users-groups/index.md
index 23c91c3fd..177cb7e38 100644
--- a/docs/backend/users-groups/index.md
+++ b/docs/backend/users-groups/index.md
@@ -1,20 +1,20 @@
 ---
 myst:
   html_meta:
-    "description": "Managing Users And Groups in Plone"
-    "property=og:description": "Managing Users And Groups in Plone"
-    "property=og:title": "Managing Users And Groups in Plone"
-    "keywords": "user, groups, plone"
+    "description": "Managing users and groups in Plone"
+    "property=og:description": "Managing users and groups in Plone"
+    "property=og:title": "Managing users and groups in Plone"
+    "keywords": "user, groups, Plone"
 ---
 
 (backend-users-groups-label)=
 
-# Users and Groups
+# Users and groups
 
 
 ```{toctree}
-:caption: Users and Groups
+:caption: Users and groups
 :maxdepth: 2
 
 emergency-user
-```
\ No newline at end of file
+```

From 6ca3507ef2353c69121c664c2012412adf7804aa Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Fri, 13 Sep 2024 03:03:43 -0700
Subject: [PATCH 03/10] Merge content from Plone 5 docs in
 https://5.docs.plone.org/manage/deploying/zope.html#adding-users-from-command-line

---
 docs/backend/users-groups/emergency-user.md | 48 +++++++++++++++------
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/docs/backend/users-groups/emergency-user.md b/docs/backend/users-groups/emergency-user.md
index d05e9ab1a..ab6fe4bb8 100644
--- a/docs/backend/users-groups/emergency-user.md
+++ b/docs/backend/users-groups/emergency-user.md
@@ -4,37 +4,61 @@ myst:
     "description": "Create an emergency user"
     "property=og:description": "Create an emergency user"
     "property=og:title": "Create an emergency user"
-    "keywords": "Plone, user and groups, emergency user, pip, buildout"
+    "keywords": "Plone, users, groups, emergency user, pip, buildout"
 ---
 
-
 (user-groups-emergency-user-label)=
 
 # Emergency user
 
-sometimes it is needed to create an emergency user. the password of admin ist lost or you have inherit a project without a proper documentation. The usecase: you will login as admin to your, but you can't.
+An emergency user is one that you can use to regain administrative access to a Plone site.
+If you lose the administrator password, or you inherit a project without proper documentation, you can create an emergency user.
+
+First of all, do the following steps not in a production environment!
+
+
+(user-groups-create-an-emergency-user-label)=
+
+## Create an emergency user
+
+There are two procedures to create an emergency user, depending on how you created and manage the Plone site.
+For both scenarios, the commands you run will stop the Plone site, add a new user, and start the Plone site.
+
+```{important}
+You should always stop your Plone site before adding a new user.
+```
+
+```{important}
+The new username must not be an existing one.
+Therefore you should avoid the username `admin`, but use another arbitrary name, such as `admin2`.
+```
 
-First of all, do the following steps not in a production environment! Shutdown your instance.
 
 (user-groups-emergency-user-pip-installation-label)=
 
-## Create an emergency user in a pip based Plone instance
+### pip based Plone instance
 
-```bash
+You can run the following shell commands to create an emergency user.
+
+```shell
+./venv/bin/instance stop
 ./venv/bin/addzopeuser -c instance/etc/zope.conf <user> <password>
+./venv/bin/instance start
 ```
 
-start your instance and login with the created user.
+Now you can login with the created user.
+
 
 (user-groups-emergency-user-buildout-installation-label)=
 
-## Create an emergency user in a buildout based Plone instance
+### Buildout based Plone instance
 
-With buildout and plone.recipe.zope2instance you can do
+With buildout and `plone.recipe.zope2instance`, you can run the following shell commands to create an emergency user.
 
-```bash
+```shell
+bin/instance stop
 bin/instance adduser <user> <password>
+bin/instance start
 ```
 
-start your instance and login with the created user.
-
+Now you can login with the created user.

From 33b3ad3037afdb52aefa9f13a92c99936884cb01 Mon Sep 17 00:00:00 2001
From: ale-rt <alessandro.pisa@gmail.com>
Date: Wed, 12 Feb 2025 11:17:03 +0100
Subject: [PATCH 04/10] Move the how to to the Admin guide section

---
 .../add-emergency-user.md}                    |  0
 docs/admin-guide/index.md                     |  1 +
 docs/backend/users-groups.md                  | 13 ++++++++++++
 docs/backend/users-groups/index.md            | 20 -------------------
 4 files changed, 14 insertions(+), 20 deletions(-)
 rename docs/{backend/users-groups/emergency-user.md => admin-guide/add-emergency-user.md} (100%)
 create mode 100644 docs/backend/users-groups.md
 delete mode 100644 docs/backend/users-groups/index.md

diff --git a/docs/backend/users-groups/emergency-user.md b/docs/admin-guide/add-emergency-user.md
similarity index 100%
rename from docs/backend/users-groups/emergency-user.md
rename to docs/admin-guide/add-emergency-user.md
diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md
index a4df3676f..fdfd90ea3 100644
--- a/docs/admin-guide/index.md
+++ b/docs/admin-guide/index.md
@@ -30,6 +30,7 @@ install-pip
 
 run-plone
 add-site
+add-emergency-user
 configure-zope
 add-ons
 export-import
diff --git a/docs/backend/users-groups.md b/docs/backend/users-groups.md
new file mode 100644
index 000000000..9954103d1
--- /dev/null
+++ b/docs/backend/users-groups.md
@@ -0,0 +1,13 @@
+---
+myst:
+  html_meta:
+    "description": ""
+    "property=og:description": ""
+    "property=og:title": ""
+    "keywords": ""
+---
+
+(backend-users-groups-label)=
+
+# Users and Groups
+
diff --git a/docs/backend/users-groups/index.md b/docs/backend/users-groups/index.md
deleted file mode 100644
index 177cb7e38..000000000
--- a/docs/backend/users-groups/index.md
+++ /dev/null
@@ -1,20 +0,0 @@
----
-myst:
-  html_meta:
-    "description": "Managing users and groups in Plone"
-    "property=og:description": "Managing users and groups in Plone"
-    "property=og:title": "Managing users and groups in Plone"
-    "keywords": "user, groups, Plone"
----
-
-(backend-users-groups-label)=
-
-# Users and groups
-
-
-```{toctree}
-:caption: Users and groups
-:maxdepth: 2
-
-emergency-user
-```

From 9d3abb9b0ac3a6cedf228cf394bc52b99237e3c7 Mon Sep 17 00:00:00 2001
From: ale-rt <alessandro.pisa@gmail.com>
Date: Wed, 12 Feb 2025 11:51:33 +0100
Subject: [PATCH 05/10] Add some more examples and clarifications

---
 docs/admin-guide/add-emergency-user.md | 103 +++++++++++++++++--------
 1 file changed, 71 insertions(+), 32 deletions(-)

diff --git a/docs/admin-guide/add-emergency-user.md b/docs/admin-guide/add-emergency-user.md
index ab6fe4bb8..05c49cc2c 100644
--- a/docs/admin-guide/add-emergency-user.md
+++ b/docs/admin-guide/add-emergency-user.md
@@ -1,64 +1,103 @@
 ---
 myst:
   html_meta:
-    "description": "Create an emergency user"
-    "property=og:description": "Create an emergency user"
-    "property=og:title": "Create an emergency user"
-    "keywords": "Plone, users, groups, emergency user, pip, buildout"
+    "description": "How to create an emergency user in an existing Zope instance"
+    "property=og:description": "How to create an emergency user in an existing Zope instance"
+    "property=og:title": "How to create an emergency user"
+    "keywords": "Plone, Zope, users, emergency user, administration, pip, buildout"
 ---
 
 (user-groups-emergency-user-label)=
 
-# Emergency user
+# Zope Manager Users
 
-An emergency user is one that you can use to regain administrative access to a Plone site.
-If you lose the administrator password, or you inherit a project without proper documentation, you can create an emergency user.
+Zope manager users have full access to the whole Zope instance.
 
-First of all, do the following steps not in a production environment!
+Some installation methods automatically create a zope admin user for you already.
 
+The credentials for this user are usually:
+
+- username: `admin`
+- password: `admin`
+
+There are multiple reasons why you might need to add a new Zope manager user, such as:
+
+- Your installation method did not create one.
+- You lost access to your instance.
+- You inherited a project without proper documentation.
+
+If you need to regain access to your instance, this user is also refered to as an emergency user.
+
+This guide explains how to add a Zope manager user to an existing Zope instance.
+
+```{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.
+```
 
 (user-groups-create-an-emergency-user-label)=
 
-## Create an emergency user
+## Adding a New Zope Manager User
 
-There are two procedures to create an emergency user, depending on how you created and manage the Plone site.
-For both scenarios, the commands you run will stop the Plone site, add a new user, and start the Plone site.
+There are multiple ways to create a Zope manager user, depending on how you created and managed your Zope instance.
 
 ```{important}
-You should always stop your Plone site before adding a new user.
+If you are running a standalone instance, it must be stopped before adding the user.
 ```
 
-```{important}
-The new username must not be an existing one.
-Therefore you should avoid the username `admin`, but use another arbitrary name, such as `admin2`.
+### Using the `adduser` instance command
+
+If your site was installed with `buildout`, you can add a Zope manager user via an instance script.
+
+Run the following command in the terminal:
+
+```bash
+$ bin/instance adduser username password
+Created user: username
 ```
 
+The name of the instance script might vary based on your installation.
+Replace `username` and `password` with the desired values.
 
-(user-groups-emergency-user-pip-installation-label)=
+If the user already exists:
 
-### pip based Plone instance
+- No user will be created
+- The password will not be changed
 
-You can run the following shell commands to create an emergency user.
+The command will return a message like this:
 
-```shell
-./venv/bin/instance stop
-./venv/bin/addzopeuser -c instance/etc/zope.conf <user> <password>
-./venv/bin/instance start
+```bash
+$ bin/instance adduser foo baz
+Created user: None
 ```
 
-Now you can login with the created user.
+### Using the `addzopeuser` command
 
+For `pip` based installations, you will have a script called `addzopeuser` in the `bin` directory of your virtual environment.
 
-(user-groups-emergency-user-buildout-installation-label)=
+The `addzopeuser` script might also be available in `buildout` based installations.
 
-### Buildout based Plone instance
+Run in the terminal:
 
-With buildout and `plone.recipe.zope2instance`, you can run the following shell commands to create an emergency user.
-
-```shell
-bin/instance stop
-bin/instance adduser <user> <password>
-bin/instance start
+```bash
+$ .venv/bin/addzopeuser -c path/to/etc/zope.conf username password
+User username created.
 ```
 
-Now you can login with the created user.
+The `addzopeuser` script and `zope.conf` locations might vary based on your installations.
+Replace `username` and `password` with the desired values.
+
+If the user already exists:
+
+- No user will be created
+- The password will not be changed
+
+The command will return a message like this:
+
+```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.
+```

From f5fb94418e8a7ecdcd11bebcfdf758824405718c Mon Sep 17 00:00:00 2001
From: ale-rt <alessandro.pisa@gmail.com>
Date: Fri, 14 Feb 2025 11:39:13 +0100
Subject: [PATCH 06/10] Clarify and rework the docs for adding a Zope manager
 user

---
 docs/admin-guide/add-emergency-user.md | 29 ++++++++++++++------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/docs/admin-guide/add-emergency-user.md b/docs/admin-guide/add-emergency-user.md
index 05c49cc2c..820974a0f 100644
--- a/docs/admin-guide/add-emergency-user.md
+++ b/docs/admin-guide/add-emergency-user.md
@@ -7,48 +7,49 @@ myst:
     "keywords": "Plone, Zope, users, emergency user, administration, pip, buildout"
 ---
 
-(user-groups-emergency-user-label)=
+(admin-guide-zope-manager-user-label)=
 
 # Zope Manager Users
 
 Zope manager users have full access to the whole Zope instance.
 
-Some installation methods automatically create a zope admin user for you already.
+Some installation methods automatically create a zope `admin` user for you already.
 
-The credentials for this user are usually:
-
-- username: `admin`
-- password: `admin`
+This guide explains how to add a Zope manager user to an existing Zope instance.
 
-There are multiple reasons why you might need to add a new Zope manager user, such as:
+There are multiple reasons why you might need to do that, such as:
 
 - Your installation method did not create one.
 - You lost access to your instance.
 - You inherited a project without proper documentation.
 
-If you need to regain access to your instance, this user is also refered to as an emergency user.
-
-This guide explains how to add a Zope manager user to an existing Zope instance.
+```{note}
+If you need to regain access to your instance, this user is also referred to as an **emergency user**.
+```
 
 ```{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.
 ```
 
-(user-groups-create-an-emergency-user-label)=
+(admin-guide-adding-a-new-zope-manager-user-label)=
 
 ## Adding a New Zope Manager User
 
-There are multiple ways to create a Zope manager user, depending on how you created and managed your Zope instance.
+There are multiple ways to create a Zope manager user.
+That depends on how you created and managed your Zope instance.
 
 ```{important}
 If you are running a standalone instance, it must be stopped before adding the user.
 ```
 
+(admin-guide-using-the-adduser-instance-command-label)=
+
 ### Using the `adduser` instance command
 
-If your site was installed with `buildout`, 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 an instance script.
 
 Run the following command in the terminal:
 
@@ -72,6 +73,8 @@ $ bin/instance adduser foo baz
 Created user: None
 ```
 
+(admin-guide-using-the-addzopeuser-command-label)=
+
 ### Using the `addzopeuser` command
 
 For `pip` based installations, you will have a script called `addzopeuser` in the `bin` directory of your virtual environment.

From 64b80cac6353a9ffec67ccc1484ba802ee29b87c Mon Sep 17 00:00:00 2001
From: David Glick <david@glicksoftware.com>
Date: Sun, 16 Feb 2025 20:06:29 -0800
Subject: [PATCH 07/10] Update docs/backend/index.md

---
 docs/backend/index.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/backend/index.md b/docs/backend/index.md
index 6420b3437..3f4cb3176 100644
--- a/docs/backend/index.md
+++ b/docs/backend/index.md
@@ -35,7 +35,6 @@ security
 sending-email
 subscribers
 traversal-acquisition
-users-groups/index
 vocabularies
 widgets
 workflows

From c89eb53b26b16a076afd6525cfbed2a2873659e5 Mon Sep 17 00:00:00 2001
From: David Glick <david@glicksoftware.com>
Date: Sun, 16 Feb 2025 20:19:16 -0800
Subject: [PATCH 08/10] rename file, update metadata

---
 docs/admin-guide/index.md                            |  2 +-
 .../{add-emergency-user.md => zope-manager-users.md} | 12 ++++++------
 2 files changed, 7 insertions(+), 7 deletions(-)
 rename docs/admin-guide/{add-emergency-user.md => zope-manager-users.md} (88%)

diff --git a/docs/admin-guide/index.md b/docs/admin-guide/index.md
index fdfd90ea3..a239d54e0 100644
--- a/docs/admin-guide/index.md
+++ b/docs/admin-guide/index.md
@@ -30,7 +30,7 @@ install-pip
 
 run-plone
 add-site
-add-emergency-user
+zope-manager-users
 configure-zope
 add-ons
 export-import
diff --git a/docs/admin-guide/add-emergency-user.md b/docs/admin-guide/zope-manager-users.md
similarity index 88%
rename from docs/admin-guide/add-emergency-user.md
rename to docs/admin-guide/zope-manager-users.md
index 820974a0f..69d2fc183 100644
--- a/docs/admin-guide/add-emergency-user.md
+++ b/docs/admin-guide/zope-manager-users.md
@@ -1,15 +1,15 @@
 ---
 myst:
   html_meta:
-    "description": "How to create an emergency user in an existing Zope instance"
-    "property=og:description": "How to create an emergency user in an existing Zope instance"
-    "property=og:title": "How to create an emergency user"
-    "keywords": "Plone, Zope, users, emergency user, administration, pip, buildout"
+    "description": "How to create a Zope manager user in an existing Zope instance"
+    "property=og:description": "How to create a Zope manager user in an existing Zope instance"
+    "property=og:title": "Zope manager users"
+    "keywords": "Plone, Zope, users, admin user, emergency user, administration, pip, buildout"
 ---
 
 (admin-guide-zope-manager-user-label)=
 
-# Zope Manager Users
+# Zope manager users
 
 Zope manager users have full access to the whole Zope instance.
 
@@ -36,7 +36,7 @@ You might want to change the passwords of the already existing manager users aft
 
 (admin-guide-adding-a-new-zope-manager-user-label)=
 
-## Adding a New Zope Manager User
+## 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.

From 45aa742c2350842846853d354621bbc96b2cac6d Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Mon, 17 Feb 2025 02:06:43 -0800
Subject: [PATCH 09/10] Restore users-groups

See https://github.com/plone/documentation/issues/1410
---
 docs/backend/index.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/backend/index.md b/docs/backend/index.md
index 3f4cb3176..3e7dd3278 100644
--- a/docs/backend/index.md
+++ b/docs/backend/index.md
@@ -35,6 +35,7 @@ security
 sending-email
 subscribers
 traversal-acquisition
+users-groups
 vocabularies
 widgets
 workflows

From c6611109167bdfea6fb57e98c86eb9bbf476f51e Mon Sep 17 00:00:00 2001
From: Steve Piercy <web@stevepiercy.com>
Date: Mon, 17 Feb 2025 02:07:20 -0800
Subject: [PATCH 10/10] Polish up Zope manager users (#1867)

* Polish up Zope manager users

* Consistent indents of 4 spaces
---
 docs/admin-guide/zope-manager-users.md | 97 +++++++++++++-------------
 1 file changed, 50 insertions(+), 47 deletions(-)

diff --git a/docs/admin-guide/zope-manager-users.md b/docs/admin-guide/zope-manager-users.md
index 69d2fc183..4093567c7 100644
--- a/docs/admin-guide/zope-manager-users.md
+++ b/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.
+-   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.
+    ```