CTRT for the Reset user passwords topic

doc/raketasks/index.md

@@ -45,6 +45,7 @@ The following Rake tasks are available for use with GitLab:
 | [SMTP maintenance](../administration/raketasks/smtp.md) | SMTP-related tasks. |
 | [SPDX license list import](spdx.md)                   | Import a local copy of the [SPDX license list](https://spdx.org/licenses/) for matching [License Compliance policies](../user/compliance/license_compliance/index.md). |
 | [Repository storage](../administration/raketasks/storage.md) | List and migrate existing projects and attachments from legacy storage to hashed storage. |
+| [Reset user passwords](../security/reset_user_password.md#use-a-rake-task) | Reset user passwords using Rake. |
 | [Uploads migrate](../administration/raketasks/uploads/migrate.md) | Migrate uploads between local storage and object storage. |
 | [Uploads sanitize](../administration/raketasks/uploads/sanitize.md) | Remove EXIF data from images uploaded to earlier versions of GitLab. |
 | [Service Data](../administration/troubleshooting/gitlab_rails_cheat_sheet.md#generate-service-ping) | Generate and troubleshoot [Service Ping](../development/service_ping/index.md). |

doc/raketasks/user_management.md

@@ -176,3 +176,7 @@ cp config/secrets.yml.bak config/secrets.yml
 sudo /etc/init.d/gitlab start
 
 ```
+
+## Related topics
+
+- [Reset a user's password](../security/reset_user_password.md#use-a-rake-task).

doc/security/reset_user_password.md

@@ -5,68 +5,83 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 type: howto
 ---
 
-# How to reset user password **(FREE SELF)**
+# Reset a user's password **(FREE SELF)**
 
-There are a few ways to reset the password of a user.
+You can reset user passwords by using a Rake task, a Rails console, or the
+[Users API](../api/users.md#user-modification).
 
-## Rake Task
+## Prerequisites
+
+To reset a user password, you must be an administrator of a self-managed GitLab instance.
+
+## Use a Rake task
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/52347) in GitLab 13.9.
 
-GitLab provides a Rake Task to reset passwords of users using their usernames,
-which can be invoked by the following command:
+Use the following Rake task to reset a user's password:
 
-```shell
-sudo gitlab-rake "gitlab:password:reset"
-```
+- **For Omnibus installations**
 
-GitLab asks for a username, a password, and a password confirmation. Upon giving
-proper values for them, the password of the specified user is updated.
+  ```shell
+  sudo gitlab-rake "gitlab:password:reset"
+  ```
 
-The Rake task also takes the username as an argument, as shown in the example
-below:
+- **For installations from source**
 
-```shell
-sudo gitlab-rake "gitlab:password:reset[johndoe]"
-```
+  ```shell
+  bundle exec rake "gitlab:password:reset"
+  ```
 
-NOTE:
-To reset the default admin password, run this Rake task with the username
-`root`, which is the default username of that administrator account.
+GitLab requests a username, a password, and confirmation of the password. When complete, the user's password is updated.
 
-## Rails console
+The Rake task can take a username as an argument. For example, to reset the password for the user with username
+`sidneyjones`:
 
-The Rake task is capable of finding users via their usernames. However, if only
-user ID or email ID of the user is known, Rails console can be used to find user
-using user ID and then change password of the user manually.
+- **For Omnibus installations**
 
-1. [Start a Rails console](../administration/operations/rails_console.md)
+  ```shell
+  sudo gitlab-rake "gitlab:password:reset[sidneyjones]"
+  ```
+
+- **For installations from source**
 
-1. Find the user either by username, user ID or email ID:
+  ```shell
+  bundle exec rake "gitlab:password:reset[sidneyjones]"
+  ```
+
+## Use a Rails console
+
+If you know the username, user ID, or email address, you can use the Rails console to reset their password:
+
+1. Open a [Rails console](../administration/operations/rails_console.md).
+1. Find the user:
+
+   - By username:
 
      ```ruby
      user = User.find_by_username 'exampleuser'
+     ```
 
-    #or
+   - By user ID:
 
+     ```ruby
      user = User.find(123)
+     ```
 
-    #or
+   - By email address: 
 
+     ```ruby
      user = User.find_by(email: 'user@example.com')
      ```
       
-1. Reset the password
+1. Reset the password:
 
    ```ruby
    user.password = 'secret_pass'
    user.password_confirmation = 'secret_pass'
     ```
 
-1. When using this method instead of the [Users API](../api/users.md#user-modification),
-   GitLab sends an email to the user stating that the user changed their
-   password. If the password was changed by an administrator, execute the
-   following command to notify the user by email:
+1. Optional. Notify the user that an administrator changed their password:
 
    ```ruby
    user.send_only_admin_changed_your_password_notification!
@@ -78,48 +93,32 @@ using user ID and then change password of the user manually.
     user.save!
     ```
 
-1. Exit the console, and then try to sign in with your new password.
+1. Exit the console:
+
+   ```ruby
+   exit
+   ```
 
-NOTE:
-You can also reset passwords by using the [Users API](../api/users.md#user-modification).
+## Reset the root password
 
-## Password reset does not appear to work
+To reset the root password, follow the steps listed previously.
 
-If you can't sign on with the new password, it might be because of the [reconfirmation feature](../user/upgrade_email_bypass.md).
+- If the root account name hasn't changed, use the username `root`.
+- If the root account name has changed and you don't know the new username,
+  you might be able to use a Rails console with user ID `1`. In almost all 
+  cases, the first user is the default administrator account.
 
-Try fixing this on the rails console. For example, if your new `root` password isn't working:
+## Troubleshooting
 
-1. [Start a Rails console](../administration/operations/rails_console.md).
+If the new password doesn't work, it might be [an email confirmation issue](../user/upgrade_email_bypass.md). You can
+attempt to fix this issue in a Rails console. For example, if a new `root` password isn't working:
 
-1. Find the user and skip reconfirmation, using any of the methods above:
+1. Start a [Rails console](../administration/operations/rails_console.md).
+1. Find the user and skip reconfirmation:
 
     ```ruby
     user = User.find(1)
     user.skip_reconfirmation!
     ```
 
-1. Try to sign in again.
-
-## Reset your root password
-
-The previously described steps can also be used to reset the root password.
-
-In normal installations where the username of root account hasn't been changed
-manually, the Rake task can be used with username `root` to reset the root
-password.
-
-If the username was changed to something else and has been forgotten, one
-possible way is to reset the password using Rails console with user ID `1` (in
-almost all the cases, the first user is the default administrator account).
-
-<!-- ## Troubleshooting
-
-Include any troubleshooting steps that you can foresee. If you know beforehand what issues
-one might have when setting this up, or when something is changed, or on upgrading, it's
-important to describe those, too. Think of things that may go wrong and include them here.
-This is important to minimize requests for support, and to avoid doc comments with
-questions that you know someone might ask.
-
-Each scenario can be a third-level heading, e.g. `### Getting error message X`.
-If you have none to add when creating a doc, leave this section in place
-but commented out to help encourage others to add to it in the future. -->
+1. Attempt to sign in again.