Update documentation for foreman-rake permissions:reset (#4327)

Co-authored-by: Aneta Šteflová Petrová <[email protected]>

Author: jafiala

guides/common/modules/proc_resetting-the-administrative-user-password.adoc

@@ -4,46 +4,44 @@
 = Resetting the administrative user password
 
 [role="_abstract"]
-Use the following procedures to reset the administrative password to randomly generated characters or to set a new administrative password.
+You can reset the administrative password to randomly generated characters or set a new administrative password for a specific user.
+This might be useful when you forget the password, when the administrative user is deleted, or for assigning administrative privileges to a user.
 
 .Procedure
-. To reset the administrative user password:
-.. Log in to the base operating system where {ProjectServer} is installed.
-.. Enter the following command to reset the password:
+. Log in to the base operating system where your {ProjectServer} is installed.
+. Reset the administrative user password:
+* To set a randomly generated administrative user password:
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
 # foreman-rake permissions:reset
 Reset to user: admin, password: qwJxBptxb7Gfcjj5
 ----
-.. Use this password to reset the password in the {ProjectWebUI}.
-.. Edit the `~/.hammer/cli.modules.d/foreman.yml` file on {ProjectServer} to add the new password:
+
+* To set a new administrative user password:
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
-# vi ~/.hammer/cli.modules.d/foreman.yml
+# foreman-rake permissions:reset username=_My_User_Name_ password=_My_New_Password_
 ----
 +
+Replace `_My_User_Name_` with the username of the user whose password you want to reset.
++
 [NOTE]
 ====
-Unless you update the `~/.hammer/cli.modules.d/foreman.yml` file, you cannot use the new password with Hammer CLI.
+Be aware of the following behaviors:
+
+* If you enter a username that does not exist, the `foreman-rake` utility creates a new administrative user with the defined password.
+* If you enter a username of a user without administrative privileges, that user gains administrative privileges.
+* If you do not enter a username, the password resets for the `admin` user by default.
 ====
-. To set a new administrative user password
-.. Log in to the base operating system where {ProjectServer} is installed.
-.. To set the password, enter the following command:
-+
-[options="nowrap", subs="+quotes,verbatim,attributes"]
-----
-# foreman-rake permissions:reset password=_new_password_
-----
-.. Edit the `~/.hammer/cli.modules.d/foreman.yml` file on {ProjectServer} to add the new password:
+
+. To use the new password with the Hammer CLI, add the password and username to the `~/.hammer/cli.modules.d/foreman.yml` file on your {ProjectServer}:
 +
 [options="nowrap", subs="+quotes,verbatim,attributes"]
 ----
 # vi ~/.hammer/cli.modules.d/foreman.yml
 ----
-+
-[NOTE]
-====
-Unless you update the `~/.hammer/cli.modules.d/foreman.yml` file, you cannot use the new password with Hammer CLI.
-====
+
+.Verification
+* Use the new password to log in to the {ProjectWebUI}.