Merge branch 'docs-aqualls-cleanup5' into 'master'

Re-flow notes back into body text

See merge request gitlab-org/gitlab!46841

doc/administration/feature_flags.md

@@ -36,8 +36,8 @@ error, it's very important that you [**provide feedback**](https://gitlab.com/gi
 as possible so we can improve or fix it while behind a flag. When you upgrade
 GitLab to an earlier version, the feature flag status may change.
 
-NOTE: **Note:**
-Mind that features deployed behind feature flags may not be ready for
+CAUTION: **Caution:**
+Features deployed behind feature flags may not be ready for
 production use. However, disabling features behind flags that were deployed
 enabled by default may also present a risk. If they're enabled, we recommend
 you leave them as-is.

doc/administration/monitoring/prometheus/gitlab_exporter.md

@@ -13,7 +13,6 @@ The [GitLab exporter](https://gitlab.com/gitlab-org/gitlab-exporter) enables you
 measure various GitLab metrics pulled from Redis and the database in Omnibus GitLab
 instances.
 
-NOTE: **Note:**
 For installations from source you must install and configure it yourself.
 
 To enable the GitLab exporter in an Omnibus GitLab instance:

doc/administration/monitoring/prometheus/gitlab_metrics.md

@@ -13,7 +13,6 @@ To enable the GitLab Prometheus metrics:
 1. Find the **Metrics - Prometheus** section, and click **Enable Prometheus Metrics**.
 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect.
 
-NOTE: **Note:**
 For installations from source you must configure it yourself.
 
 ## Collecting the metrics

doc/administration/monitoring/prometheus/index.md

@@ -31,7 +31,6 @@ dashboard tool like [Grafana](https://grafana.com).
 
 ## Configuring Prometheus
 
-NOTE: **Note:**
 For installations from source, you must install and configure it yourself.
 
 Prometheus and its exporters are on by default, starting with GitLab 9.0.
@@ -54,7 +53,7 @@ To disable Prometheus and all of its exporters, as well as any added in the futu
 
 ### Changing the port and address Prometheus listens on
 
-NOTE: **Note:**
+CAUTION: **Caution:**
 The following change was added in [Omnibus GitLab 8.17](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/1261). Although possible,
 it's not recommended to change the port Prometheus listens
 on, as this might affect or conflict with other services running on the GitLab
@@ -178,7 +177,6 @@ The next step is to tell all the other nodes where the monitoring node is:
 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to
    take effect.
 
-NOTE: **Note:**
 After monitoring using Service Discovery is enabled with `consul['monitoring_service_discovery'] =  true`,
 ensure that `prometheus['scrape_configs']` is not set in `/etc/gitlab/gitlab.rb`. Setting both
 `consul['monitoring_service_discovery'] = true` and `prometheus['scrape_configs']` in `/etc/gitlab/gitlab.rb`
@@ -186,7 +184,7 @@ will result in errors.
 
 ### Using an external Prometheus server
 
-NOTE: **Note:**
+CAUTION: **Caution:**
 Prometheus and most exporters don't support authentication. We don't recommend exposing them outside the local network.
 
 A few configuration changes are required to allow GitLab to be monitored by an external Prometheus server. External servers are recommended for [GitLab deployments with multiple nodes](../../reference_architectures/index.md).

doc/administration/monitoring/prometheus/node_exporter.md

@@ -9,7 +9,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 The [node exporter](https://github.com/prometheus/node_exporter) enables you to measure
 various machine resources such as memory, disk and CPU utilization.
 
-NOTE: **Note:**
 For installations from source you must install and configure it yourself.
 
 To enable the node exporter:

doc/administration/monitoring/prometheus/pgbouncer_exporter.md

@@ -11,7 +11,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 The [PgBouncer exporter](https://github.com/prometheus-community/pgbouncer_exporter) enables
 you to measure various [PgBouncer](https://www.pgbouncer.org/) metrics.
 
-NOTE: **Note:**
 For installations from source you must install and configure it yourself.
 
 To enable the PgBouncer exporter:

doc/administration/monitoring/prometheus/postgres_exporter.md

@@ -8,7 +8,6 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 The [PostgreSQL Server Exporter](https://github.com/wrouesnel/postgres_exporter) allows you to export various PostgreSQL metrics.
 
-NOTE: **Note:**
 For installations from source you must install and configure it yourself.
 
 To enable the PostgreSQL Server Exporter:

doc/administration/monitoring/prometheus/redis_exporter.md

@@ -10,7 +10,6 @@ The [Redis exporter](https://github.com/oliver006/redis_exporter) enables you to
 various [Redis](https://redis.io) metrics. For more information on what is exported,
 [read the upstream documentation](https://github.com/oliver006/redis_exporter/blob/master/README.md#whats-exported).
 
-NOTE: **Note:**
 For installations from source you must install and configure it yourself.
 
 To enable the Redis exporter:

doc/administration/object_storage.md

@@ -116,7 +116,7 @@ See the section on [ETag mismatch errors](#etag-mismatch) for more details.
     gitlab_rails['object_store']['objects']['terraform_state']['bucket'] = '<terraform-state>'
     ```
 
-   NOTE: For GitLab 9.4 or later, if you're using AWS IAM profiles, be sure to omit the
+   For GitLab 9.4 or later, if you're using AWS IAM profiles, be sure to omit the
    AWS access key and secret access key/value pairs. For example:
 
    ```ruby
@@ -263,9 +263,9 @@ Here are the valid connection parameters for GCS:
 | `google_json_key_location` | The JSON key path | `/path/to/gcp-project-12345-abcde.json` |
 | `google_application_default` | Set to `true` to use [Google Cloud Application Default Credentials](https://cloud.google.com/docs/authentication/production#automatically) to locate service account credentials. |
 
-NOTE: **Note:**
-The service account must have permission to access the bucket.
-[See more](https://cloud.google.com/storage/docs/authentication)
+The service account must have permission to access the bucket. Learn more
+in Google's
+[Cloud Storage authentication documentation](https://cloud.google.com/storage/docs/authentication).
 
 ##### Google example (consolidated form)
 

doc/administration/pseudonymizer.md

@@ -50,7 +50,6 @@ To configure the pseudonymizer, you need to:
    }
    ```
 
-   NOTE: **Note:**
    If you are using AWS IAM profiles, be sure to omit the AWS access key and secret access key/value pairs.
 
    ```ruby

doc/administration/raketasks/doctor.md

@@ -21,7 +21,6 @@ Automatic resolution is not yet implemented. If you have values that
 cannot be decrypted, you can follow steps to reset them, see our
 docs on what to do [when the secrets file is lost](../../raketasks/backup_restore.md#when-the-secrets-file-is-lost).
 
-NOTE: **Note:**
 This can take a very long time, depending on the size of your
 database, as it checks all rows in all tables.
 

doc/administration/raketasks/maintenance.md

@@ -130,7 +130,6 @@ sudo gitlab-rake gitlab:check
 bundle exec rake gitlab:check RAILS_ENV=production
 ```
 
-NOTE: **Note:**
 Use `SANITIZE=true` for `gitlab:check` if you want to omit project names from the output.
 
 Example output:

doc/administration/raketasks/storage.md

@@ -74,7 +74,7 @@ To have a summary and then a list of projects and their attachments using hashed
 
 ## Migrate to hashed storage
 
-NOTE: **Note:**
+DANGER: **Deprecated:**
 In GitLab 13.0, [hashed storage](../repository_storage_types.md#hashed-storage)
 is enabled by default and the legacy storage is deprecated.
 Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab
@@ -115,7 +115,6 @@ If you find it necessary, you can run this migration script again to schedule mi
 
 Any error or warning will be logged in Sidekiq's log file.
 
-NOTE: **Note:**
 If [Geo](../geo/index.md) is enabled, each project that is successfully migrated
 generates an event to replicate the changes on any **secondary** nodes.
 
@@ -124,7 +123,7 @@ commands below that helps you inspect projects and attachments in both legacy an
 
 ## Rollback from hashed storage to legacy storage
 
-NOTE: **Deprecated:**
+DANGER: **Deprecated:**
 In GitLab 13.0, [hashed storage](../repository_storage_types.md#hashed-storage)
 is enabled by default and the legacy storage is deprecated.
 Support for legacy storage will be removed in GitLab 14.0. If you're on GitLab

doc/administration/raketasks/uploads/migrate.md

@@ -16,11 +16,10 @@ There is a Rake task for migrating uploads between different storage types.
 After [configuring the object storage](../../uploads.md#using-object-storage) for GitLab's
 uploads, use this task to migrate existing uploads from the local storage to the remote storage.
 
-Read more about using [object storage with GitLab](../../object_storage.md).
-
-NOTE: **Note:**
 All of the processing will be done in a background worker and requires **no downtime**.
 
+Read more about using [object storage with GitLab](../../object_storage.md).
+
 ### All-in-one Rake task
 
 GitLab provides a wrapper Rake task that migrates all uploaded files (for example avatars, logos,
@@ -99,7 +98,6 @@ gitlab-rake "gitlab:uploads:migrate[DesignManagement::DesignV432x230Uploader, De
 
 **Source Installation**
 
-NOTE: **Note:**
 Use `RAILS_ENV=production` for every task.
 
 ```shell

doc/administration/reply_by_email_postfix_setup.md

@@ -91,9 +91,10 @@ The instructions make the assumption that you will be using the email address `i
    quit
    ```
 
-   _**Note:** The `.` is a literal period on its own line._
+   NOTE: **Note:**
+   The `.` is a literal period on its own line.
 
-   _**Note:** If you receive an error after entering `rcpt to: incoming@localhost`
+   If you receive an error after entering `rcpt to: incoming@localhost`
    then your Postfix `my_network` configuration is not correct. The error will
    say 'Temporary lookup failure'. See
    [Configure Postfix to receive email from the Internet](#configure-postfix-to-receive-email-from-the-internet)._
@@ -164,11 +165,11 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
       q
       ```
 
-   _**Note:** If `mail` returns an error `Maildir: Is a directory` then your
+   If `mail` returns an error `Maildir: Is a directory` then your
    version of `mail` doesn't support Maildir style mailboxes. Install
    `heirloom-mailx` by running `sudo apt-get install heirloom-mailx`. Then,
    try the above steps again, substituting `heirloom-mailx` for the `mail`
-   command._
+   command.
 
 1. Sign out of the `incoming` account, and go back to being `root`:
 
@@ -271,7 +272,8 @@ Courier, which we will install later to add IMAP authentication, requires mailbo
       quit
       ```
 
-      (Note: The `.` is a literal period on its own line)
+      NOTE: **Note:**
+      The `.` is a literal period on its own line.
 
    1. Check if the `incoming` user received the email:
 

doc/administration/smime_signing_email.md

@@ -9,8 +9,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 Notification emails sent by GitLab can be signed with S/MIME for improved
 security.
 
-NOTE: **Note:**
-Please be aware that S/MIME certificates and TLS/SSL certificates are not the
+Be aware that S/MIME certificates and TLS/SSL certificates are not the
 same and are used for different purposes: TLS creates a secure channel, whereas
 S/MIME signs and/or encrypts the message itself
 
@@ -27,7 +26,7 @@ files must be provided:
 Optionally, you can also provide a bundle of CA certs (PEM-encoded) to be
 included on each signature. This will typically be an intermediate CA.
 
-NOTE: **Note:**
+CAUTION: **Caution:**
 Be mindful of the access levels for your private keys and visibility to
 third parties.
 
@@ -45,7 +44,6 @@ third parties.
 
 1. Save the file and [reconfigure GitLab](restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect.
 
-NOTE: **Note:**
 The key needs to be readable by the GitLab system user (`git` by default).
 
 **For installations from source:**
@@ -69,7 +67,6 @@ The key needs to be readable by the GitLab system user (`git` by default).
 
 1. Save the file and [restart GitLab](restart_gitlab.md#installations-from-source) for the changes to take effect.
 
-NOTE: **Note:**
 The key needs to be readable by the GitLab system user (`git` by default).
 
 ### How to convert S/MIME PKCS#12 / PFX format to PEM encoding

doc/administration/timezone.md

@@ -21,7 +21,7 @@ To see all available time zones, run `bundle exec rake time:zones:all`.
 For Omnibus installations, run `gitlab-rake time:zones:all`.
 
 NOTE: **Note:**
-Currently, this Rake task does not list timezones in TZInfo format required by Omnibus GitLab during a reconfigure: [#27209](https://gitlab.com/gitlab-org/gitlab/-/issues/27209).
+This Rake task does not list timezones in TZInfo format required by Omnibus GitLab during a reconfigure: [#27209](https://gitlab.com/gitlab-org/gitlab/-/issues/27209).
 
 ## Changing time zone in Omnibus installations
 

doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md

@@ -308,11 +308,11 @@ pp p.statistics  # compare with earlier values
 
 ### Recreate
 
-A Projects Wiki can be recreated by
-
-NOTE: **Note:**
+CAUTION: **Caution:**
 This is a destructive operation, the Wiki will be empty.
 
+A Projects Wiki can be recreated by this command:
+
 ```ruby
 p = Project.find_by_full_path('<username-or-group>/<project-name>')  ### enter your projects path
 

doc/administration/troubleshooting/kubernetes_cheat_sheet.md

@@ -70,8 +70,7 @@ and they will assist you with any issues you are having.
   kubectl logs <pod-name> --previous
   ```
 
-  NOTE: **Note:**
-  No logs are kept in the containers/pods themselves, everything is written to stdout.
+  No logs are kept in the containers/pods themselves. Everything is written to stdout.
   This is the principle of Kubernetes, read [Twelve-factor app](https://12factor.net/)
   for details.
 

doc/administration/troubleshooting/linux_cheat_sheet.md

@@ -18,7 +18,6 @@ If you are administering GitLab you are expected to know these commands for your
 of choice. If you are a GitLab Support Engineer, consider this a cross-reference to
 translate `yum` -> `apt-get` and the like.
 
-Note: **Note:**
 Most of the commands below have not been labeled as to which distribution they work
 on. Contributions are welcome to help add them.
 

doc/administration/troubleshooting/navigating_gitlab_via_rails_console.md

@@ -385,7 +385,7 @@ User.find_by(username: 'root')
 User.find_by_any_email('user@example.com')
 ```
 
-Note: `find_by_any_email` is a custom method added by GitLab developers rather
+The `find_by_any_email` method is a custom method added by GitLab developers rather
 than a Rails-provided default method.
 
 **Get a collection of admin users:**
@@ -394,7 +394,7 @@ than a Rails-provided default method.
 User.admins
 ```
 
-Note: `admins` is a [scope convenience method](https://guides.rubyonrails.org/active_record_querying.html#scopes)
+`admins` is a [scope convenience method](https://guides.rubyonrails.org/active_record_querying.html#scopes)
 which does `where(admin: true)` under the hood.
 
 **Get a project by its path:**
@@ -403,7 +403,7 @@ which does `where(admin: true)` under the hood.
 Project.find_by_full_path('group/subgroup/project')
 ```
 
-Note: `find_by_full_path` is a custom method added by GitLab developers rather
+`find_by_full_path` is a custom method added by GitLab developers rather
 than a Rails-provided default method.
 
 **Get a project's issue or merge request by its numeric ID:**
@@ -414,7 +414,7 @@ project.issues.find_by(iid: 42)
 project.merge_requests.find_by(iid: 42)
 ```
 
-Note: `iid` means "internal ID" and is how we keep issue and merge request IDs
+`iid` means "internal ID" and is how we keep issue and merge request IDs
 scoped to each GitLab project.
 
 **Get a group by its path:**
@@ -454,7 +454,7 @@ Ci::Pipeline.find(4151)
 Ci::Build.find(66124)
 ```
 
-Note: The pipeline and job #ID numbers increment globally across your GitLab
+The pipeline and job ID numbers increment globally across your GitLab
 instance, so there's no need to use an internal ID attribute to look them up,
 unlike with issues or merge requests.
 

doc/administration/troubleshooting/postgresql.md

@@ -148,4 +148,4 @@ It may take a little while to respond.
 ```
 
 NOTE: **Note:**
-These are Omnibus settings. If an external database, such as a customer's PostgreSQL installation or Amazon RDS is being used, these values don't get set, and would have to be set externally.
+These are Omnibus GitLab settings. If an external database, such as a customer's PostgreSQL installation or Amazon RDS is being used, these values don't get set, and would have to be set externally.

doc/administration/troubleshooting/sidekiq.md

@@ -13,12 +13,10 @@ may be filling up. Users will notice when this happens because new branches
 may not show up and merge requests may not be updated. The following are some
 troubleshooting steps that will help you diagnose the bottleneck.
 
-NOTE: **Note:**
 GitLab administrators/users should consider working through these
 debug steps with GitLab Support so the backtraces can be analyzed by our team.
 It may reveal a bug or necessary improvement in GitLab.
 
-NOTE: **Note:**
 In any of the backtraces, be wary of suspecting cases where every
 thread appears to be waiting in the database, Redis, or waiting to acquire
 a mutex. This **may** mean there's contention in the database, for example,
@@ -133,7 +131,6 @@ corresponding Ruby code where this is happening.
 `gdb` can be another effective tool for debugging Sidekiq. It gives you a little
 more interactive way to look at each thread and see what's causing problems.
 
-NOTE: **Note:**
 Attaching to a process with `gdb` will suspends the normal operation
 of the process (Sidekiq will not process jobs while `gdb` is attached).
 
@@ -284,15 +281,15 @@ end
 
 ### Remove Sidekiq jobs for given parameters (destructive)
 
-The general method to kill jobs conditionally is the following:
+The general method to kill jobs conditionally is the following command, which
+will remove jobs that are queued but not started. Running jobs will not be killed.
 
 ```ruby
 queue = Sidekiq::Queue.new('<queue name>')
 queue.each { |job| job.delete if <condition>}
 ```
 
-NOTE: **Note:**
-This will remove jobs that are queued but not started, running jobs will not be killed. Have a look at the section below for cancelling running jobs.
+Have a look at the section below for cancelling running jobs.
 
 In the method above, `<queue-name>` is the name of the queue that contains the job(s) you want to delete and `<condition>` will decide which jobs get deleted.
 
@@ -300,7 +297,6 @@ Commonly, `<condition>` references the job arguments, which depend on the type o
 
 For example, `repository_import` has `project_id` as the job argument, while `update_merge_requests` has `project_id, user_id, oldrev, newrev, ref`.
 
-NOTE: **Note:**
 Arguments need to be referenced by their sequence ID using `job.args[<id>]` because `job.args` is a list of all arguments provided to the Sidekiq job.
 
 Here are some examples: