Apply suggestions from code review

AbstractionFactory · jeremy-albinet · virtualroot · web-flow · commit b8c6fb9f7ccd · 2024-10-11T10:20:38.000+02:00
Co-authored-by: Jeremy Albinet &lt;3602453+jeremy-albinet@users.noreply.github.com&gt;
Co-authored-by: Alejandro Lazaro &lt;virtualroot@users.noreply.github.com&gt;
Signed-off-by: AbstractionFactory &lt;179820029+abstractionfactory@users.noreply.github.com&gt;
diff --git a/frontend/docs/modules/adding.md b/frontend/docs/modules/adding.md
@@ -2,10 +2,10 @@
 
 Once you have [published your module](/docs/modules/publishing), you can add your module to the OpenTofu Registry. You can do this by [creating an issue](https://github.com/opentofu/registry/issues/new/choose) on the OpenTofu Registry GitHub repository.
 
-Here you will have to provide your username and repository name, which will translate to a module name. For example, consider the following repository:
+Here you will have to provide your username/organization name and repository name, which will translate to a module name. For example, consider the following repository:
 
 ```
 YOURNAME/terraform-NAME-TARGETSYSTEM
 ```
 
-This will translate to a module address your users can reference it as `YOURNAME/NAME/TARGETSYSTEM`.
+This will translate to a module address your users can reference as `YOURNAME/NAME/TARGETSYSTEM`.
diff --git a/frontend/docs/providers/adding.md b/frontend/docs/providers/adding.md
@@ -16,4 +16,4 @@ After your provider is merged, you can proceed to add your GPG key. You will nee
 4. In the `Provider Namespace` field enter your username or organization name.
 5. In the `Provider GPG Key` field paste your GPG key.
 
-~> The GPG key applies to all providers in under your username or organization. Don't submit a GPG key if you have providers that are not signed or are signed with a key you don't have.
+~> The GPG key applies to all providers under your username or organization. Don't submit a GPG key if you have providers that are not signed or are signed with a key you don't have.
diff --git a/frontend/docs/providers/docs.md b/frontend/docs/providers/docs.md
@@ -4,7 +4,7 @@ In order for your provider to show up in the OpenTofu Registry Search properly,
 
 ## Documentation structure
 
-You can place your documentation in the `docs` or `website/docs` folder in your repository. Please create the files in the following naming convention:
+You can place your documentation in the `docs` folder in your repository. Please create the files using the following naming convention:
 
 - `/docs/guides/<guide>.md` for guides.
 - `/docs/resources/<resource>.md` for resources. (Note: if your resource is called `yourprovider_yourresource`, you should only include `yourresource` here.)
diff --git a/frontend/docs/providers/publishing.md b/frontend/docs/providers/publishing.md
@@ -8,7 +8,11 @@ Once you have finished [creating your provider](/docs/providers/creating) and [w
 
 If you used the [terraform-provider-scaffolding-framework](https://github.com/hashicorp/terraform-provider-scaffolding-framework) as your starting point, it also includes the necessary GitHub Actions and [goreleaser file](https://github.com/hashicorp/terraform-provider-scaffolding-framework/blob/main/.goreleaser.yml) needed to create a release.
 
-You will need to create the secrets called `GPG_PRIVATE_KEY` and `PASSPHRASE` in order to sign your release. This is required for the Terraform Registry and recommended for the OpenTofu Registry.  Please follow the [GitHub documentation on generating a GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). (You do not need to add it to your GitHub account, but you will need to [submit the key to the OpenTofu Registry](/docs/providers/adding) in the next step).
+You will need to create the secrets called `GPG_PRIVATE_KEY` and `PASSPHRASE` in order to sign your release. GPG keys ensure the integrity of your provider binaries. While OpenTofu allows you to submit a provider without a GPG key for compatibility reasons, adding a GPG key helps keep your users safe and is also required if you intend to submit your provider to the Terraform Registry. The workflow in the terraform-provider-scaffolding-framework repository assumes you will use a GPG key.
+
+Please follow the [GitHub documentation on generating a GPG key](https://docs.github.com/en/authentication/managing-commit-signature-verification/generating-a-new-gpg-key). You do not need to add the public key to your GitHub account, but instead you can [submit it to the OpenTofu Registry](/docs/providers/adding) in the next step.
+
+~> Keep your private key safe! If your private key becomes public, others will be able to produce correctly signed binaries for your provider! The private key should only be in your GitHub secrets and backed up on your own computer. You should never need to submit the private key anywhere.
 
 Once this is set up, proceed to create a release named `vYOURVERSION` on GitHub and wait for the GitHub Actions job to complete.
 
diff --git a/frontend/docs/users/index.md b/frontend/docs/users/index.md
@@ -1,6 +1,6 @@
 # The OpenTofu Registry for Users
 
-OpenTofu is but a tool that works with integrations made by the community called *providers*. In addition to that, community-made modules simplify many common tasks. The OpenTofu Registry contains an index pointing to thousands of providers and tends of thousands of modules on GitHub you can use. You can install them automatically by adding a code snippet to your project and running `tofu init`.
+OpenTofu is a tool that works with integrations made by the community called *providers*. In addition to that, community-made modules simplify many common tasks. The OpenTofu Registry contains an index pointing to thousands of providers and thousands of modules on GitHub you can use. You can install them automatically by adding a code snippet to your project and running `tofu init`.
 
 ## In this chapter
 
diff --git a/frontend/docs/users/modules.md b/frontend/docs/users/modules.md
@@ -1,6 +1,6 @@
 # Using a module
 
-Modules provide reusable pieces of code for your OpenTofu project. The OpenTofu Registry contains references to over 20.000 modules on GitHub created by the community. You can [find a module for your use case using the OpenTofu Registry Search](https://search.opentofu.org/modules/). You can learn more about how modules work in OpenTofu from the [OpenTofu documentation](https://opentofu.org/docs/language/modules/). 
+Modules provide reusable pieces of code for your OpenTofu project. The OpenTofu Registry contains references to over 20,000 modules on GitHub created by the community. You can [find a module for your use case using the OpenTofu Registry Search](https://search.opentofu.org/modules/). You can learn more about how modules work in OpenTofu from the [OpenTofu documentation](https://opentofu.org/docs/language/modules/). 
 
 ~> The OpenTofu Registry does not perform security scanning on modules, and they may contain malicious code. Inspect any module you intend to use and only use modules from authors you trust.
 
diff --git a/frontend/docs/users/providers.md b/frontend/docs/users/providers.md
@@ -1,6 +1,6 @@
 # Using a provider
 
-Providers give OpenTofu the ability to call various APIs. The OpenTofu registry currently holds over 4000 such providers created by the community. They provide integrations for a vast range of services, from cloud providers, such as [AWS](https://search.opentofu.org/provider/hashicorp/aws/latest), [Azure](https://search.opentofu.org/provider/hashicorp/azurerm/latest), [GCP](https://search.opentofu.org/provider/hashicorp/google/latest) and more, version control systems, such as [GitHub](https://search.opentofu.org/provider/integrations/github/latest), [Gitlab](https://search.opentofu.org/provider/gitlabhq/gitlab/latest), to password manages like [1Password](https://search.opentofu.org/provider/1password/onepassword/latest). You can explore the providers available [using the OpenTofu Registry Search](https://search.opentofu.org/providers/) or learn more about how providers work in OpenTofu using the [OpenTofu documentation](https://opentofu.org/docs/language/providers/).
+Providers give OpenTofu the ability to call various APIs. The OpenTofu registry currently holds over 4000 such providers created by the community. They provide integrations for a vast range of services, from cloud providers, such as [AWS](https://search.opentofu.org/provider/hashicorp/aws/latest), [Azure](https://search.opentofu.org/provider/hashicorp/azurerm/latest), [GCP](https://search.opentofu.org/provider/hashicorp/google/latest) and more, version control systems, such as [GitHub](https://search.opentofu.org/provider/integrations/github/latest), [GitLab](https://search.opentofu.org/provider/gitlabhq/gitlab/latest), to password manages like [1Password](https://search.opentofu.org/provider/1password/onepassword/latest). You can explore the providers available [using the OpenTofu Registry Search](https://search.opentofu.org/providers/) or learn more about how providers work in OpenTofu using the [OpenTofu documentation](https://opentofu.org/docs/language/providers/).
 
 ~> Providers are binary programs created by their authors that run on your machine. The OpenTofu Registry does not perform security scanning on providers, and they may contain malicious code. There is also no guarantee that the provider binary was compiled from the code in the linked GitHub repository. Only use providers from authors you trust.
 
