docs: update based on suggestions from code review

docs/Homebrew-brew-Maintainer-Guide.md

@@ -1,11 +1,11 @@
-# `brew` Maintainer Guide
+# Homebrew/brew Maintainer Guide
 
 This document describes a few components of the `Homebrew/brew` repository that are useful for maintainers to
 be aware of, but don't necessarily need to appear in documentation for most users and contributors.
 
 ## Reviewing PRs
 
-Using `gh repo checkout NUMBER` is a super easy way to check out a PR branch using the GitHub CLI.
+Using `gh pr checkout NUMBER` is a super easy way to check out a PR branch using the GitHub CLI.
 
 When reviewing, choose the "comment" type for reviews when the PR isn't quite ready to be merged.
 Use the "approve" type when you feel that the PR is in a good state to be merged, even if there are
@@ -95,4 +95,4 @@ merged. These follow-up PRs can be merged immediately if the changes seem correc
 An update can be requested manually by triggering the workflow from the
 [Update maintainers, manpage and completions](https://github.com/Homebrew/brew/actions/workflows/update-man-completions.yml)
 section under the "Actions" tab. Click on the "Run workflow" dropdown and then the "Run workflow" button.
-A PR will be opened shorty if there are any changes.
+A PR will be opened shortly if there are any changes.

docs/Homebrew-homebrew-cask-Maintainer-Guide.md

@@ -1,4 +1,4 @@
-# Cask Maintainer Guide
+# Homebrew/homebrew-cask Maintainer Guide
 
 This guide is intended to help maintainers effectively maintain the cask repositories.
 It is meant to be used in conjunction with the more generic [Maintainer Guidelines](Maintainer-Guidelines.md).
@@ -14,7 +14,7 @@ This guide applies to all four of the cask repositories:
 
 Here is a list of the most common situations that arise in PRs and how to handle them:
 
-- The `version` and `sha256` both change (keeping the same format): Merge
+- The `version` and `sha256` both change (keeping the same format): Merge.
 - Only the `sha256` changes: Merge unless the version needs to be updated as well.
   It’s not uncommon for upstream vendors to update versions in-place.
 - `livecheck` is updated: Use your best judgement and try to make sure that the changes
@@ -31,11 +31,12 @@ Note that unlike in formulae, casks do not consider the `sha256` stanza as meani
 
 ### Approvals
 
-In general, PRs in the cask repositories should have at least one approval from a maintainer
+PRs in the cask repositories should must have at least one approval
-before being merged.
+from a user with write access before they can be merged.
 
-If desired, a maintainer can self-approve one of their PRs using the
+Ideally, this approval will come from another maintainer. If necessary, however, a maintainer
-`self-approve` GitHub Actions workflow to satisfy this requirement. To trigger a self-approval, navigate to the
+can self-approve one of their PRs using the `self-approve` GitHub Actions workflow to satisfy
+this requirement. To trigger a self-approval, navigate to the
 ["Self-approve a Pull Request" section of the Actions tab](https://github.com/Homebrew/homebrew-cask/actions/workflows/self-approve.yml),
 click on "Run workflow", enter the PR number and click "Run workflow".
 

docs/Homebrew-homebrew-core-Merge-Checklist.md

@@ -1,4 +1,4 @@
-# Core Maintainer Guide
+# Homebrew/homebrew-core Maintainer Guide
 
 ## Quick merge checklist
 
@@ -23,10 +23,6 @@ forever. Nobody really checks if they are necessary or not.
 Depend on as little stuff as possible. Disable X11 functionality if possible.
 For example, we build Wireshark, but not the heavy GUI.
 
-For [some formulae](https://github.com/Homebrew/homebrew-core/search?q=%22homebrew%2Fmirror%22&unscoped_q=%22homebrew%2Fmirror%22),
-we mirror the tarballs to our own BinTray automatically as part of the
-bottle publish CI run.
-
 Homebrew is about Unix software. Stuff that builds to an `.app` should
 be in Homebrew Cask instead.
 
@@ -39,6 +35,9 @@ Choose a name that’s the most common name for the project.
 For example, we initially chose `objective-caml` but we should have chosen `ocaml`.
 Choose what people say to each other when talking about the project.
 
+Formulae that are also packaged by other package managers (e.g. Debian, Ubuntu) should be
+named consistently (subject to minor differences due to Homebrew formula naming conventions).
+
 Add other names as aliases as symlinks in `Aliases` in the tap root. Ensure the
 name referenced on the homepage is one of these, as it may be different and have
 underscores and hyphens and so on.
@@ -117,6 +116,9 @@ Formulae that:
 
 should not be removed from Homebrew. The exception to this rule are [versioned formulae](Versions.md) for which there are higher standards of usage and a maximum number of versions for a given formula.
 
+For more information about deprecating, disabling and removing formulae, see the
+[Deprecating, Disabling, and Removing Formulae page](Deprecating-Disabling-and-Removing-Formulae.md)
+
 ## Detailed merge checklist
 
 The following checklist is intended to help maintainers decide on

docs/Homebrew-linuxbrew-core-Maintainer-Guide.md

@@ -1,4 +1,4 @@
-# Linux Maintainer Guide
+# Homebrew/linuxbrew-core Maintainer Guide
 
 ## Merging formulae updates from Homebrew/homebrew-core
 

docs/Maintainer-Guidelines.md

@@ -13,16 +13,19 @@ All Homebrew maintainers are encouraged to contribute to all parts of the projec
 but there are four main teams that maintainers tend to be a part of:
 
 - `brew` maintainers: this team maintains the [`Homebrew/brew`](https://github.com/Homebrew/brew) repository.
-  See the [`brew` Maintainer Guide](Brew-Maintainer-Guide.md) for more details about being a `brew` maintainer.
+  See the [Homebrew/brew Maintainer Guide](Homebrew-brew-Maintainer-Guide.md) for more details about being a `brew` maintainer.
 - Core maintainers: this team maintains the [`Homebrew/homebrew-core`](https://github.com/Homebrew/homebrew-core)
-  repository. See the [Core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md) for more details about being a core maintainer.
+  repository. See the [Homebrew/homebrew-core Maintainer Guide](Homebrew-homebrew-core-Merge-Checklist.md)
+  for more details about being a core maintainer.
 - Linux maintainers: this team maintains the [`Homebrew/linuxbrew-core`](https://github.com/Homebrew/linuxbrew-core)
-  repository. See the [Linux Maintainer Guide](Linux-Maintainer-Guide.md) for more details about being a Linux maintainer.
+  repository. See the [Homebrew/linuxbrew-core Maintainer Guide](Homebrew-linuxbrew-core-Maintainer-Guide.md)
+  for more details about being a Linux maintainer.
 - Cask maintainers: this team maintains the [`Homebrew/homebrew-cask`](https://github.com/Homebrew/homebrew-cask),
   [`Homebrew/homebrew-cask-drivers`](https://github.com/Homebrew/homebrew-cask-drivers),
   [`Homebrew/homebrew-cask-fonts`](https://github.com/Homebrew/homebrew-cask-fonts) and
   [`Homebrew/homebrew-cask-versions`](https://github.com/Homebrew/homebrew-cask-versions) repositories.
-  See the [Cask Maintainer Guide](Cask-Maintainer-Guide.md) for more details about being a cask maintainer.
+  See the [Homebrew/homebrew-cask Maintainer Guide](Homebrew-homebrew-cask-Maintainer-Guide.md)
+  for more details about being a cask maintainer.
 
 These documents are meant to serve as guiding principles. As a maintainer, you can make a call to either
 request changes from a contributor or help them out based on their comfort and previous contributions.