cleanup: update contributing guide (#11861)

Co-authored-by: Sebastiaan Speck <12570668+sebastiaanspeck@users.noreply.github.com>

CONTRIBUTING.md

@@ -33,7 +33,7 @@ The basic format of a `tldr` page is a set of concrete usage examples.
 
 Here are a few guidelines to get started:
 
-1. Try to keep pages at around 5 examples. Pages can be longer or shorter when appropriate, but don't exceed the maximum of eight examples.
+1. Try to keep pages at around 5 examples. Pages can be longer or shorter when appropriate but don't exceed the maximum of eight examples.
    Remember, it's OK if the page doesn't cover everything; that's what `man` is for.
 2. When in doubt, keep new command-line users in mind. Err on the side of clarity rather than terseness.
    For example, commands that require `sudo` should include it directly in the examples.
@@ -71,7 +71,7 @@ As a quick reference, the format of each page should match the following templat
 For page descriptions, you can additionally use ``See also: `command`.`` and [subcommand reference](#subcommands).
 
 > [!NOTE]
-> While we suggest only two lines for the page description, it is acceptable to have more than two lines if it necessary to add additional information (i.e. [`pacman`](https://github.com/tldr-pages/tldr/blob/main/pages/linux/pacman.md)).
+> While we suggest only two lines for the page description, it is acceptable to have more than two lines if it is necessary to add additional information (i.e. [`pacman`](https://github.com/tldr-pages/tldr/blob/main/pages/linux/pacman.md)).
 
 To see some examples of preexisting pages, you can look at:
 
@@ -98,21 +98,44 @@ To create a page for a subcommand, the program and subcommand need to be separat
 
 You should always add a base page (e.g. `git`) that describes the program and basic switches like `--version` or `--help`.
 
-To let others know about the subcommand, add a note saying ``Some subcommands such as `example command` have their own usage documentation`` to the base page.
+### Referencing subcommands
+
+The following methods can be used to reference subcommands:
+
+- You can add a note saying ``Some subcommands such as `example command` have their own usage documentation`` to the main page. (See the [subcommand reference](/contributing-guides/translation-templates/subcommand-mention.md) page for translation templates.)
+- You can use ``See also: `command1`, `command2`.`` template to reference similar commands, aliases and subcommands.
+- Alternatively, the whole page can be converted to reference the main subcommands.
+
+For example:
+
+```md
+# command
+
+> Short, snappy description.
+> Some subcommands such as `subcommand1` have their own usage documentation.
+> More information: <https://url-to-upstream.tld>.
+
+- View documentation for creating something:
+
+`tldr command-subcommand1`
+
+- View documentation for managing something:
+
+`tldr command-subcommand2`
+```
 
 See these examples for reference:
 
 - [git](pages/common/git.md)
-- [git-commit](pages/common/git-commit.md)
-- [aws](pages/common/aws.md)
-- [aws-s3](pages/common/aws-s3.md)
+- [distrobox-create](pages/linux/distrobox-create.md)
+- [nmcli](pages/linux/nmcli.md)
 
 ## Translations
 
 Translation of pages can be done by simply creating the corresponding page within the appropriate language-specific directory, creating that as well if it does not already exist.
 
 > [!IMPORTANT]
-> Translations of pages should be done based on the English (US) page in the `pages` directory. If the English pages doesn't exist for the command, it should be added first in a PR before creating a translation.
+> Translations of pages should be done based on the English (US) page in the `pages` directory. If the English pages don't exist for the command, it should be added first in a PR before creating a translation.
 
 Language specific directories must follow the pattern `pages.<locale>`, where `<locale>` is a [POSIX Locale Name](https://www.gnu.org/software/gettext/manual/html_node/Locale-Names.html#Locale-Names) in the form of `<language>[_<country>]`, where:
 
@@ -124,6 +147,9 @@ The `<country>` code is optional and should only be added when it is needed. In
 > [!IMPORTANT]  
 > When adding a new language to `tldr`, it is suggested to add it to the [translation templates](contributing-guides/translation-templates) along with any page additions.
 
+> [!TIP]
+> When fixing errors in an existing translation, it is suggested to update the page to match the latest version of the English page.
+
 To see the current progress of all translations, you can visit <https://lukwebsforge.github.io/tldri18n/>, which provides a dynamically updated table of all pages and their translations.
 
 Some examples of valid locale tags:
@@ -137,7 +163,7 @@ A list of translated templates for alias pages can be found [here](contributing-
 
 It is acceptable for several pages to get translated in one pull request.
 
-For more information about language specific rules, refer to the [style guide](contributing-guides/style-guide.md#language-specific-rules).
+For more information about language-specific rules, refer to the [style guide](contributing-guides/style-guide.md#language-specific-rules).
 
 ## Inclusive language
 
@@ -165,7 +191,7 @@ tldr-lint {{path/to/page.md}}
 Now, you are ready to submit a pull request!
 
 > [!TIP]
-> Additionally, inside the `tldr` directory you can install the dependencies using `npm install` command and now when you commit your changes, the tests will run automatically via the pre-commit hook.
+> Additionally, inside the `tldr` directory you can install the dependencies using the `npm install` command and now when you commit your changes, the tests will run automatically via the pre-commit hook. (To skip the pre-commit hook and immediately commit your changes use the `git commit --no-verify` command).
 
 ### Submitting changes
 
@@ -188,7 +214,7 @@ To commit a suggestion to your pull request, click on `Commit suggestion`:
 
 ![Commit suggestion button in Github](./images/commit-suggestion-button.png)
 
-If you want to commit multiple suggestions, go to the "Files changed" tab and batch all suggestions. Now, click `Commit suggestions` button and enter a commit message to create a single commit.
+If you want to commit multiple suggestions, go to the "Files changed" tab and batch all suggestions. Now, click the `Commit suggestions` button and enter a commit message to create a single commit.
 
 ### Commit message
 
@@ -206,10 +232,16 @@ Where `{{command}}` is the name of the command being modified, and `type of chan
 - For multiple subcommand page additions: `git-{add, push, ...}: add page`
 - For modifying multiple pages in a language: `pages.<locale>/*: update pages`
 
----
-
 For other cases, its suggested to follow <https://www.conventionalcommits.org/> as much as possible.
 
+## Name collisions
+
+When there are multiple commands sharing the same name, the existing page of the command and the new command can be renamed to `command.1` and so on following a numbering scheme or based on the programming language i.e. `command.js`. The base page can be updated to reference the newly renamed/created pages by following [this subcommand reference format](#subcommands).
+
+See the following page for reference:
+
+- [just](pages/common/just.md)
+
 ## Licensing
 
 This repository is licensed under the [Creative Commons Attribution 4.0 International License](LICENSE.md).