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

Re-flow notes back into body text

See merge request gitlab-org/gitlab!46838

doc/development/application_limits.md

@@ -33,7 +33,6 @@ It's recommended to create two separate migration script files.
    add_column(:plan_limits, :project_hooks, :integer, default: 100, null: false)
    ```
 
-   NOTE: **Note:**
    Plan limits entries set to `0` mean that limits are not enabled. You should
    use this setting only in special and documented circumstances.
 
@@ -64,7 +63,6 @@ It's recommended to create two separate migration script files.
    end
    ```
 
-   NOTE: **Note:**
    Some plans exist only on GitLab.com. This will be a no-op for plans
    that do not exist.
 
@@ -103,7 +101,6 @@ can be used to validate that a model does not exceed the limits. It ensures
 that the count of the records for the current model does not exceed the defined
 limit.
 
-NOTE: **Note:**
 You must specify the limit scope of the object being validated
 and the limit name if it's different from the pluralized model name.
 
@@ -152,5 +149,4 @@ GitLab.com:
 - `silver` - Namespaces and projects with a Silver subscription
 - `gold` - Namespaces and projects with a Gold subscription
 
-NOTE: **Note:**
-The test environment doesn't have any plans.
+The `test` environment doesn't have any plans.

doc/development/architecture.md

@@ -687,7 +687,6 @@ Sidekiq is a Ruby background job processor that pulls jobs from the Redis queue
 
 #### Puma
 
-NOTE: **Note:**
 Starting with GitLab 13.0, Puma is the default web server and Unicorn has been
 disabled by default.
 
@@ -705,7 +704,6 @@ disabled by default.
 
 #### Unicorn
 
-NOTE: **Note:**
 Starting with GitLab 13.0, Puma is the default web server and Unicorn has been
 disabled by default.
 
@@ -1021,9 +1019,9 @@ PostgreSQL:
 GitLab has configuration files located in `/home/git/gitlab/config/*`. Commonly referenced
 configuration files include:
 
-- `gitlab.yml` - GitLab configuration
-- `puma.rb` - Puma web server settings
-- `database.yml` - Database connection settings
+- `gitlab.yml`: GitLab configuration
+- `puma.rb`: Puma web server settings
+- `database.yml`: Database connection settings
 
 GitLab Shell has a configuration file at `/home/git/gitlab-shell/config.yml`.
 
@@ -1039,9 +1037,12 @@ bundle exec rake gitlab:env:info RAILS_ENV=production
 bundle exec rake gitlab:check RAILS_ENV=production
 ```
 
-Note: It is recommended to log into the `git` user using `sudo -i -u git` or `sudo su - git`. While
-the `sudo` commands provided by GitLab work in Ubuntu they do not always work in RHEL.
+It's recommended to sign in to the `git` user using either `sudo -i -u git` or
+`sudo su - git`. Although the `sudo` commands provided by GitLab work in Ubuntu,
+they don't always work in RHEL.
 
 ## GitLab.com
 
-We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/) but this is probably over the top unless you have millions of users.
+The [GitLab.com architecture](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/)
+is detailed for your reference, but this architecture is only useful if you have
+millions of users.

doc/development/documentation/feature_flags.md

@@ -30,7 +30,6 @@ See how to document them below, according to the state of the flag:
 - [Features that can be enabled or disabled for a single project](#features-enabled-by-project).
 - [Features with the feature flag removed](#features-with-flag-removed).
 
-NOTE: **Note:**
 The [`**(CORE ONLY)**`](styleguide.md#product-badges) badge or equivalent for
 the feature's tier should be added to the line and heading that refers to
 enabling/disabling feature flags as Admin access is required to do so,

doc/development/documentation/site_architecture/global_nav.md

@@ -70,7 +70,6 @@ With these groups in mind, the following are general rules for where new items s
 - Other documentation belongs at the top-level, but care must be taken to not create an enormously
   long top-level navigation, which defeats the purpose of it.
 
-NOTE: **Note:**
 Making all documentation and navigation items adhere to these principles is being progressively
 rolled out.
 
@@ -117,7 +116,6 @@ for clarity.
 To see the improvements planned, check the
 [global nav epic](https://gitlab.com/groups/gitlab-com/-/epics/21).
 
-NOTE: **Note:**
 **Do not** [add items](#adding-new-items) to the global nav without
 the consent of one of the technical writers.
 

doc/development/documentation/site_architecture/index.md

@@ -230,8 +230,9 @@ for its search function. This is how it works:
    there's a JavaScript snippet which initiates DocSearch by using an API key
    and an index name (`gitlab`) that are needed for Algolia to show the results.
 
-NOTE: **For GitLab Team Members:**
-If you’re a GitLab Team Member, find credentials for the Algolia dashboard
+### Algolia notes for GitLab team members
+
+If you’re a GitLab team member, find credentials for the Algolia dashboard
 in the shared [GitLab 1Password account](https://about.gitlab.com/handbook/security/#1password-for-teams).
 To receive weekly reports of the search usage, search the Google doc with
 title `Email, Slack, and GitLab Groups and Aliases`, search for `docsearch`,

doc/development/documentation/site_architecture/release_process.md

@@ -15,7 +15,6 @@ Since the charts use a different version number than all the other GitLab
 products, we need to add a
 [version mapping](https://docs.gitlab.com/charts/installation/version_mappings.html):
 
-NOTE: **Note:**
 The charts stable branch is not created automatically like the other products.
 There's an [issue to track this](https://gitlab.com/gitlab-org/charts/gitlab/-/issues/1442).
 It is usually created on the 21st or the 22nd.
@@ -164,7 +163,7 @@ Releasing a new version is a long process that involves many moving parts.
 
 ### `test_internal_links_and_anchors` failing on dropdown merge requests
 
-NOTE: **Note:**
+DANGER: **Deprecated:**
 We now pin versions in the `.gitlab-ci.yml` of the respective branch,
 so the steps below are deprecated.
 

doc/development/documentation/structure.md

@@ -230,7 +230,6 @@ Consider the following guidelines when offering examples:
 - Better and best cases can be considered part of the good case(s) code block.
   In the same code block, precede each with comments: `# Better` and `# Best`.
 
-NOTE: **Note:**
 Although the bad-then-good approach is acceptable for the GitLab development
 guidelines, do not use it for user documentation. For user documentation, use
 *Do* and *Don't*. For examples, see the [Pajamas Design System](https://design.gitlab.com/content/punctuation/).

doc/development/documentation/workflow.md

@@ -10,7 +10,6 @@ The process for creating and maintaining GitLab product documentation allows
 anyone to contribute a merge request or create an issue for GitLab's
 documentation.
 
-NOTE: **Note:**
 Documentation updates relating to new features or feature enhancements must
 use the [feature workflow process](https://about.gitlab.com/handbook/engineering/ux/technical-writing/workflow/#for-a-product-change) described in the GitLab Handbook.
 
@@ -165,6 +164,5 @@ Ensure the following if skipping an initial Technical Writer review:
   - For [directories and files](styleguide.md#work-with-directories-and-files).
   - For [images](styleguide.md#images).
 
-NOTE: **Note:**
 Merge requests that change the location of documentation must always be reviewed by a Technical
 Writer prior to merging.

doc/development/feature_flags/controls.md

@@ -213,7 +213,6 @@ actors.
 Feature.enabled?(:some_feature, group)
 ```
 
-NOTE: **Note:**
 **Percentage of time** rollout is not a good idea if what you want is to make sure a feature
 is always on or off to the users. In that case, **Percentage of actors** rollout is a better method.
 

doc/development/feature_flags/development.md

@@ -35,7 +35,6 @@ used so that unfinished code can be deployed in production.
 A `development` feature flag should have a rollout issue,
 ideally created using the [Feature Flag Roll Out template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/issue_templates/Feature%20Flag%20Roll%20Out.md).
 
-NOTE: **Note:**
 This is the default type used when calling `Feature.enabled?`.
 
 ### `ops` type
@@ -356,7 +355,6 @@ Introducing a feature flag into the codebase creates an additional code path tha
 It is strongly advised to test all code affected by a feature flag, both when **enabled** and **disabled**
 to ensure the feature works properly.
 
-NOTE: **Note:**
 When using the testing environment, all feature flags are enabled by default.
 
 To disable a feature flag in a test, use the `stub_feature_flags`

doc/development/feature_flags/index.md

 ---
-type: index, dev
 stage: none
 group: Development
 info: "See the Technical Writers assigned to Development Guidelines: https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments-to-development-guidelines"

doc/development/file_storage.md

@@ -56,10 +56,10 @@ In the case of Issues/MR/Notes Markdown attachments, there is a different approa
 instead of basing the path into a mutable variable `:project_path_with_namespace`, it's possible to use the
 hash of the project ID instead, if project migrates to the new approach (introduced in 10.2).
 
-> Note: We provide an [all-in-one Rake task](../administration/raketasks/uploads/migrate.md) to migrate all uploads to object
-> storage in one go. If a new Uploader class or model type is introduced, make
-> sure you add a Rake task invocation corresponding to it to the
-> [category list](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/uploads/migrate.rake).
+We provide an [all-in-one Rake task](../administration/raketasks/uploads/migrate.md)
+to migrate all uploads to object storage in one go. If a new Uploader class or model
+type is introduced, make sure you add a Rake task invocation corresponding to it to the
+[category list](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/tasks/gitlab/uploads/migrate.rake).
 
 ### Path segments
 
@@ -107,7 +107,7 @@ The `CarrierWave::Uploader#store_dir` is overridden to
 
 ### Using `ObjectStorage::Extension::RecordsUploads`
 
-> Note: this concern will automatically include `RecordsUploads::Concern` if not already included.
+This concern will automatically include `RecordsUploads::Concern` if not already included.
 
 The `ObjectStorage::Concern` uploader will search for the matching `Upload` to select the correct object store. The `Upload` is mapped using `#store_dirs + identifier` for each store (LOCAL/REMOTE).
 

doc/development/gotchas.md

@@ -163,7 +163,7 @@ allow_next_found_instance_of(Project) do |project|
 end
 ```
 
-_**Note:** Since Active Record is not calling the `.new` method on model classes to instantiate the objects,
+Since Active Record is not calling the `.new` method on model classes to instantiate the objects,
 you should use `expect_next_found_instance_of` or `allow_next_found_instance_of` mock helpers to setup mock on objects returned by Active Record query & finder methods._
 
 If we also want to initialize the instance with some particular arguments, we
@@ -188,7 +188,7 @@ refresh_service.execute(oldrev, newrev, ref)
 
 See ["Why is it bad style to `rescue Exception => e` in Ruby?"](https://stackoverflow.com/questions/10048173/why-is-it-bad-style-to-rescue-exception-e-in-ruby).
 
-_**Note:** This rule is [enforced automatically by
+This rule is [enforced automatically by
 RuboCop](https://gitlab.com/gitlab-org/gitlab-foss/blob/8-4-stable/.rubocop.yml#L911-914)._
 
 ## Do not use inline JavaScript in views
@@ -196,8 +196,8 @@ RuboCop](https://gitlab.com/gitlab-org/gitlab-foss/blob/8-4-stable/.rubocop.yml#
 Using the inline `:javascript` Haml filters comes with a
 performance overhead. Using inline JavaScript is not a good way to structure your code and should be avoided.
 
-_**Note:** We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/hamlit.rb)
-in an initializer._
+We've [removed these two filters](https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/hamlit.rb)
+in an initializer.
 
 ### Further reading
 

doc/development/licensing.md

@@ -18,7 +18,8 @@ Some gems may not include their license information in their `gemspec` file, and
 
 ### License Finder commands
 
-> Note: License Finder currently uses GitLab misused terms of `whitelist` and `blacklist`. As a result, the commands below reference those terms. We've created an [issue on their project](https://github.com/pivotal/LicenseFinder/issues/745) to propose that they rename their commands.
+NOTE: **Note:**
+License Finder currently uses GitLab misused terms of `whitelist` and `blacklist`. As a result, the commands below reference those terms. We've created an [issue on their project](https://github.com/pivotal/LicenseFinder/issues/745) to propose that they rename their commands.
 
 There are a few basic commands License Finder provides that you'll need in order to manage license detection.