Add improvements to modules, services, and contributions pages

_docs-sources/library/overview/modules.md

@@ -1,24 +1,44 @@
 # What is a module?
 
-Modules are reusable "infrastructure building blocks" that encapsulate the configuration and resource definitions needed to deploy and manage a specific piece of infrastructure, such as a VPC, ECS cluster, or Auto Scaling Group. Each module defines several AWS resources. For example, the VPC module contains resource definitions for subnets, NAT gateways, and more. Modules promote code reusability, modularity, and consistency in infrastructure deployments and can be customized in a variety of ways.
+Modules are reusable "infrastructure building blocks" that describe how to deploy and manage a specific piece of infrastructure, such as a VPC, ECS cluster, or Auto Scaling Group.
 
-Gruntwork modules are tested in AWS, in a randomly selected region, each time it changes to verify the infrastructure created matches the desired configuration.
+Most modules are written in Terraform and define several AWS resources.
 
 ## Example
 
-Let’s look at an example module. The [rds module](/reference/modules/terraform-aws-data-storage/rds/) creates an RDS database, the IAM roles needed to operate that database, optional read replicas, database subnet groups, and the relevant security groups.
+Let’s look at an example module. The [rds module](/reference/modules/terraform-aws-data-storage/rds/) is a Terraform module that creates an RDS database, the IAM roles needed to operate that database, optional read replicas, database subnet groups, and the relevant security groups.
 
-The module is written in Terraform and is a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup, or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves! Indeed, `backup-plan`, `backup-vault`, and `rds-proxy` can all be used in combination with the `rds` module.
+The module deploys a key element of an overall RDS deployment, but it's not a _complete_ RDS deployment. That's because the `rds` module does not include backup policies using AWS Backup (for disaster recovery), or RDS Proxy (to pool database connections), or CloudWatch alarms (to alert you when something goes wrong). These missing pieces are best thought of as building block modules themselves. Gruntwork has modules for `backup-plan`, `backup-vault`, and `rds-proxy` that can all be used in combination with the `rds` module.
 
 To see how Gruntwork gives you an off-the-shelf overall deployment with all the elements included, see [What is a service module?](./services.md).
 
-## When should I use a module?
+## Modules are optimized for control
 
-The Gruntwork Infrastructure as Code (IaC) Library contains [hundreds of modules](/library/reference/) that you can use and combine. These modules are fairly generic building blocks, so you don’t typically deploy a single module directly. Instead, you write code that combines the modules you need for a specific use case.
+A module is designed to be small, narrow in scope, and highly reusable, like a building block. Modules give you _control_, but they may not give you _convenience_. You can use the building block modules for all kinds of use cases (high control), but if you want to deploy a complete piece of infrastructure, you still have to do the work of assembling the right modules (low convenience).
+
+To learn how you can optimize for convenience, see [What is a service module?](./services.md).
+
+To learn more about the overall thought process behind building block modules versus service modules, see [Introducing: The Gruntwork Module, Service, and Architecture Catalogs](https://blog.gruntwork.io/introducing-the-gruntwork-module-service-and-architecture-catalogs-eb3a21b99f70).
+
+## When to use a building block module
+
+Building block modules are fairly generic by design, so you won't typically deploy a single building block module directly. Instead, you write code that combines the building block modules you need for a specific use case.
 
 For example, one module might deploy the control plane for Kubernetes and a separate module could deploy worker nodes; you may need to combine both modules together to deploy a Kubernetes cluster.
 
-We recommend our [Service Catalog](/library/overview/services/) for common use cases, but our full Module Catalog is available if you have a more complex use case. For a full list of modules available, refer to the [Gruntwork Infrastructure as Code Library](/library/reference/).
+We recommend our [Service Catalog](/library/overview/services/) for common use cases, but our full module catalog is available if you have a more complex use case.
+
+## Where to find the building block modules
+
+The module catalog features over 250 "building block" modules spanning three major use cases:
+
+1. AWS foundations
+2. Running applications
+3. Storing data
+
+Each of these use cases covers one or more Subject Matter Expert (SME) topics such as AWS account management, VPC/Networking, EKS, ECS, and RDS. SME topics are a first-class concept within Gruntwork, but do not have much visibility in the product itself at this time.
+
+To browse the module catalog, see the [Library Reference](/library/reference/) and look for "Module Catalog" on the sidebar. You can also visit the list of [private Gruntwork GitHub repos](https://github.com/orgs/gruntwork-io/repositories?q=&type=private&language=&sort=).
 
 ## How modules are structured
 
@@ -31,3 +51,9 @@ The code in the module repos are organized into three primary folders:
 1. `test`: Automated tests for the code in modules and examples.
 
 We follow Hashicorp's [Standard Model Structure](https://developer.hashicorp.com/terraform/language/modules/develop/structure) for our files (`main.tf`, `variables.tf`, `outputs.tf`). In the `variables.tf` file we always put the required variables at the top of the file, followed by the optional variables. Although there are often a lot of ways to configure our modules, we set reasonable defaults and try to minimize the effort required to configure the modules to the most common use cases.
+
+## How modules are updated
+
+Gruntwork brings together AWS and Terraform experts around the world who track updates from AWS, Terraform, and the DevOps community at large, along with requests from the Gruntwork customer community. We translate the most important of these updates into new features, new optimizations, and ultimately new releases.
+
+Refer to [Gruntwork releases](/guides/stay-up-to-date/#gruntwork-releases) for a comprehensive listing of all the updates.

_docs-sources/library/overview/services.md

@@ -1,16 +1,40 @@
 # What is a service module?
 
-The Gruntwork Service Catalog consists of a number of customizable, production-grade infrastructure-as-code services that you can use to deploy and manage your infrastructure. This includes Docker orchestration, EC2 orchestration, load balancing, networking, databases, caches, monitoring, alerting, CI/CD, secrets management, VPN, and much more. Services combine multiple modules to configure an end-to-end solution.
+Service modules are combinations of [modules](./modules) covering a wide variety of use cases, including CI/CD, networking, container orchestration (EKS, ECS), and more. Service modules are usually written in Terraform, represent a full use case, and are designed to be used "off the shelf."
 
-## When should I use a service?
+## Example
 
-Using a service can save you time piecing together individual modules and testing that they’re correctly referencing each other. These are designed for specific use cases such as EKS and ECS clusters, VPCs with public and private subnets, and databases.
+Let’s look at an example service module. The [`rds` service module](/reference/services/data-storage/amazon-rds) creates not only an RDS database, but also a DNS record in Amazon Route53, CloudWatch alarms, a CloudWatch dashboard, and scheduled snapshots of the database, all using a combination of "building block" modules.
 
-For example, the `eks-cluster` service combines all the modules you need to run an EKS (Kubernetes) cluster in a typical production environment, including modules for the control plane, worker nodes, secrets management, log aggregation, alerting, and so on.
+After applying, you will have an RDS instance that you can access via a human-friendly name, alarms to alert you if something goes wrong, a dashboard for viewing RDS KPIs, and a strategy for disaster recovery.
 
-If you need more flexibility than our services provide, then you can combine modules from our [Module Catalog](./modules.md), your own modules, or open source modules to meet your specific use case.
+## Service modules are optimized for convenience
 
-CIS customers also have access to the `terraform-aws-cis-service-catalog` repository to help ensure conformity to the [CIS AWS Foundations Benchmark](https://gruntwork.io/achieve-compliance/).
+Whereas "building block" modules are optimized for control, service modules are optimized for convenience.
+
+A service module reflects a complete Gruntwork opinion on how you should run a piece of infrastructure. Using a service module gives you the convenience of a single Terraform module that does everything you need, with Gruntwork maintaining the code.
+
+If you do not agree with our opinions, you can either [customize the module](/library/usage/customizing-modules), or sacrifice convenience in favor of control and build your own module, possibly out of our [building block modules](/library/overview/modules).
+
+## When to use a service module
+
+Using a service module can save you time because Gruntwork has already pieced together individual building block modules and tested that they correctly reference each other.
+
+For example, the [eks-cluster service module](/reference/services/app-orchestration/amazon-eks) combines all the modules you need to run an EKS (Kubernetes) cluster in a typical production environment, including modules for the control plane, worker nodes, secrets management, log aggregation, alerting, and so on.
+
+If you need more flexibility than our services provide, then you can combine modules from our [module catalog](./modules#where-to-find-the-building-block-modules), your own modules, or open source modules to meet your specific use case.
+
+CIS customers also have access to the [terraform-aws-cis-service-catalog git repo](https://github.com/gruntwork-io/terraform-aws-service-catalog) to help ensure conformity to the [CIS AWS Foundations Benchmark](https://gruntwork.io/achieve-compliance/).
+
+## Where to find the service modules
+
+The service catalog features over 25 service modules spanning three major use cases:
+
+1. AWS foundations
+2. Running applications
+3. Storing data
+
+To browse the service catalog, see the [Library Reference](/library/reference/) and look for "Service Catalog" in the sidebar. You can also visit the [terraform-aws-service-catalog git repo](https://github.com/gruntwork-io/terraform-aws-service-catalog).
 
 ## How services are structured
 
@@ -37,3 +61,7 @@ The code in the `terraform-aws-service-catalog` repo is organized into three pri
        if there is no example?](https://github.com/gruntwork-io/knowledge-base/discussions/360#discussioncomment-25705480).
 
 1. `test`: Automated tests for the code in modules and examples.
+
+## How service modules are updated
+
+When [building block modules are updated](/library/overview/modules#how-modules-are-updated), we propagate those updates to the service catalog. Keep in mind that there is sometimes a delay between when a "building block" module is updated and when that update is reflected in the service catalog.

_docs-sources/library/usage/composing-your-own-service.md

@@ -1,6 +1,6 @@
-# Composing your own Service
+# Composing your own service module
 
-We offer a collection of [services](../overview/services.md#what-is-a-service) that piece together individual [modules](../overview/modules.md#what-is-a-module) for specific use cases such as EKS clusters and VPCs with public and private subnets. While we strive to make our service catalog as a complete as possible, you may need to create your own service to suit a specific use case or need for your company.
+We offer a collection of [service modules](../overview/services.md#what-is-a-service) that piece together individual [modules](../overview/modules.md#what-is-a-module) for specific use cases such as EKS clusters and VPCs with public and private subnets. While we strive to make our service catalog as a complete as possible, you may need to create your own service to suit a specific use case or need for your company.
 
 In this guide, you will learn how to create a service that provisions a simple API using the [AWS Lambda Function](../../reference/modules/terraform-aws-lambda/lambda/) and [API Gateway](../../reference/modules/terraform-aws-lambda/lambda-http-api-gateway/) modules from the Gruntwork Infrastructure as Code (IaC) Library.
 

_docs-sources/library/usage/contributing.md

@@ -2,29 +2,36 @@
 sidebar_label: "Contributing"
 ---
 
-# Contributing to the Gruntwork Infrastructure as Code Library
+# Contributing to Gruntwork Library
 
-Contributions to the Gruntwork Infrastructure as Code Library are very welcome and appreciated! If you find a bug or want to add a new
-feature or even contribute an entirely new module, we are very happy to accept
-[pull requests](https://help.github.com/articles/about-pull-requests/), provide feedback, and run your changes through
-our automated test suite.
+Contributions to Gruntwork Library are welcome and appreciated! In fact, Gruntwork receives over 1,000 customer [pull requests](https://help.github.com/articles/about-pull-requests/) per year.
 
-This section outlines the process for contributing.
+You can contribute to the library in several ways:
 
-## File a GitHub issue
+- Update an existing "building block" module or service module
+- Contribute a new module
+- Document a bug
 
-Before starting any work, we recommend filing a GitHub issue in the appropriate repo. This is your chance to ask
+## Start by filing a GitHub issue
+
+If you're thinking of adding a new feature, before starting any work, we recommend filing a GitHub issue in the appropriate repo. This is your chance to ask
 questions and get feedback from the maintainers and the community before you sink a lot of time into writing (possibly
 the wrong) code. If there is anything you’re unsure about, just ask!
 
-## Update the documentation
+If you're submitting a simple change such as a new variable or new output value, it may be worth opening a pull request directly, as described below.
+
+## Proceed to a pull request
+
+If it makes sense to open a pull request, follow these guidelines:
+
+### Update the documentation first
 
 We recommend updating the documentation _before_ updating any code (see
 [Readme Driven Development](http://tom.preston-werner.com/2010/08/23/readme-driven-development.html)). This ensures the
 documentation stays up to date and allows you to think through the problem at a high level before you get lost in the
 weeds of coding.
 
-## Update the tests
+### Update the tests
 
 We also recommend updating the automated tests _before_ updating any code (see
 [Test Driven Development](https://en.wikipedia.org/wiki/Test-driven_development)). That means you add or update a test
@@ -33,19 +40,19 @@ This ensures the tests stay up to date and verify all the functionality in the r
 functionality you’re adding in your contribution. The `test` folder in every repo will have documentation on how to run
 the tests locally.
 
-## Update the code
+### Update the code
 
-At this point, make your code changes and use your new test case to verify that everything is working.
+At this point, you can make your code changes and use your new test case to verify that everything is working.
 
-## Create a pull request
+### Create a pull request
 
 [Create a pull request](https://help.github.com/articles/creating-a-pull-request/) with your changes. Please make sure
 to include the following:
 
 1.  A description of the change, including a link to your GitHub issue.
 2.  Any notes on backwards incompatibility.
 
-## Merge and release
+### Merge and release
 
 The maintainers for the repo will review your code and provide feedback. If everything looks good, they will merge the
 code and release a new version.