Gloss of top docs pages (#28891)

* clarify input variables opening sentence

* adjust variables description

* claraify providers text and add learn callout

* add description to providers page

* add desscription and clarify provider configuration

* add deprecation note to versions in proivder configs

* add hands on callout and clarify next steps in intro

* link to language collection from language docs

* give more context about configurtion language up front

* clarify output top page

* reorganize for each intro to present feature before notes

* move description before link out and remove passive voice

* fix typo

* clarify purpose of plan

* move explanation before learn link and fully spell boolean

* add a syntax heading  to separate intro from details

* add learn callout to module source docs

* clean up intro to provider requirements and add link

* Apply suggestions from code review

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

website/docs/cli/commands/plan.html.md

@@ -8,18 +8,19 @@ description: |-
 
 # Command: plan
 
-> **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
+The `terraform plan` command creates an execution plan, which lets you preview
+the changes that Terraform plans to make to your infrastructure. By default,
+when Terraform creates a plan it:
 
-The `terraform plan` command creates an execution plan. By default, creating
+* Reads the current state of any already-existing remote objects to make sure
-a plan consists of:
-
-* Reading the current state of any already-existing remote objects to make sure
   that the Terraform state is up-to-date.
-* Comparing the current configuration to the prior state and noting any
+* Compares the current configuration to the prior state and noting any
   differences.
-* Proposing a set of change actions that should, if applied, make the remote
+* Proposes a set of change actions that should, if applied, make the remote
   objects match the configuration.
 
+> **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
+
 The plan command alone will not actually carry out the proposed changes, and
 so you can use this command to check whether the proposed changes match what
 you expected before you apply the changes or share your changes with your

website/docs/language/data-sources/index.html.md

@@ -8,12 +8,10 @@ description: |-
 
 # Data Sources
 
-> **Hands-on:** Try the [Query data sources](https://learn.hashicorp.com/tutorials/terraform/data-sources?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
+_Data sources_ allow Terraform use information defined outside of Terraform,
+defined by another separate Terraform configuration, or modified by functions. 
 
-_Data sources_ allow data to be fetched or computed for use elsewhere
+> **Hands-on:** Try the [Query Data Sources](https://learn.hashicorp.com/tutorials/terraform/data-sources) tutorial on HashiCorp Learn.
-in Terraform configuration. Use of data sources allows a Terraform
-configuration to make use of information defined outside of Terraform,
-or defined by another separate Terraform configuration.
 
 Each [provider](/docs/language/providers/index.html) may offer data sources
 alongside its set of [resource](/docs/language/resources/index.html)

website/docs/language/expressions/conditionals.html.md

@@ -5,10 +5,12 @@ page_title: "Conditional Expressions - Configuration Language"
 
 # Conditional Expressions
 
+A _conditional expression_ uses the value of a boolean expression to select one of
+two values.
+
 > **Hands-on:** Try the [Create Dynamic Expressions](https://learn.hashicorp.com/tutorials/terraform/expressions?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
 
-A _conditional expression_ uses the value of a bool expression to select one of
+## Syntax
-two values.
 
 The syntax of a conditional expression is as follows:
 

website/docs/language/index.html.md

@@ -8,13 +8,14 @@ page_title: "Overview - Configuration Language"
 This is the documentation for Terraform's configuration language. It is relevant
 to users of [Terraform CLI](/docs/cli/index.html),
 [Terraform Cloud](/docs/cloud/index.html), and
-[Terraform Enterprise](/docs/enterprise/index.html).
+[Terraform Enterprise](/docs/enterprise/index.html). Terraform's language is
+its primary user interface. Configuration files you write in Terraform
+language tell Terraform what plugins to install, what infrastructure to create,
+and what data to fetch. Terraform language also lets you define dependencies
+between resources and create multiple similar resources from a single
+configuration block.
 
-> **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
+> **Hands-on:** Try the [Write Terraform Configuration](https://learn.hashicorp.com/collections/terraform/configuration-language) tutorials on HashiCorp Learn.
-
-_The Terraform language is Terraform's primary user interface._ In every edition
-of Terraform, a configuration written in the Terraform language is always at the
-heart of the workflow.
 
 ## About the Terraform Language
 
@@ -115,4 +116,3 @@ resource "aws_subnet" "az" {
   cidr_block = cidrsubnet(aws_vpc.main.cidr_block, 4, count.index+1)
 }
 ```
-

website/docs/language/meta-arguments/for_each.html.md

@@ -5,14 +5,6 @@ page_title: "The for_each Meta-Argument - Configuration Language"
 
 # The `for_each` Meta-Argument
 
--> **Version note:** `for_each` was added in Terraform 0.12.6. Module support
-for `for_each` was added in Terraform 0.13, and previous versions can only use
-it with resources.
-
--> **Note:** A given resource or module block cannot use both `count` and `for_each`.
-
-> **Hands-on:** Try the [Manage Similar Resources With For Each](https://learn.hashicorp.com/tutorials/terraform/for-each?in=terraform/0-13&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
-
 By default, a [resource block](/docs/language/resources/syntax.html) configures one real
 infrastructure object (and similarly, a
 [module block](/docs/language/modules/syntax.html) includes a
@@ -22,10 +14,18 @@ pool of compute instances) without writing a separate block for each one.
 Terraform has two ways to do this:
 [`count`](/docs/language/meta-arguments/count.html) and `for_each`.
 
+> **Hands-on:** Try the [Manage Similar Resources With For Each](https://learn.hashicorp.com/tutorials/terraform/for-each?in=terraform/configuration-language) tutorial on HashiCorp Learn.
+
 If a resource or module block includes a `for_each` argument whose value is a map or
 a set of strings, Terraform will create one instance for each member of
 that map or set.
 
+-> **Version note:** `for_each` was added in Terraform 0.12.6. Module support
+for `for_each` was added in Terraform 0.13; previous versions can only use
+it with resources.
+
+-> **Note:** A given resource or module block cannot use both `count` and `for_each`.
+
 ## Basic Syntax
 
 `for_each` is a meta-argument defined by the Terraform language. It can be used

website/docs/language/modules/sources.html.md

@@ -14,6 +14,10 @@ Terraform uses this during the module installation step of `terraform init`
 to download the source code to a directory on local disk so that it can be
 used by other Terraform commands.
 
+> **Hands-on:** Try our HashiCorp Learn tutorials to use modules from [the
+> registry](https://learn.hashicorp.com/tutorials/terraform/module-use)
+>or [locally](https://learn.hashicorp.com/tutorials/terraform/module-create).
+
 The module installer supports installation from a number of different source
 types, as listed below.
 

website/docs/language/providers/configuration.html.md

@@ -3,21 +3,23 @@ layout: "language"
 page_title: "Provider Configuration - Configuration Language"
 sidebar_current: "docs-config-providers"
 description: |-
-  Providers are responsible in Terraform for managing the lifecycle of a resource: create, read, update, delete.
+  Learn how to configure provider settings and alias providers to use multiple
+  different provider configurations in the same Terraform project.
 ---
 
 # Provider Configuration
 
-Terraform relies on plugins called "providers" to interact with remote systems.
+Providers alow Terraform to interact with cloud providers, SaaS providers, and
+other APIs.
 
-Terraform configurations must declare which providers they require, so that
+Some providers require you to configure them with endpoint URLs, cloud regions,
-Terraform can install and use them. Additionally, some providers require
+or other settings before Terraform can use them. This page documents how to
-configuration (like endpoint URLs or cloud regions) before they can be used.
+configure settings for providers.
 
-- This page documents how to configure settings for providers.
+Additionally, all Terraform configurations must declare which providers they
-
+require so that Terraform can install and use them. The
-- The [Provider Requirements](/docs/language/providers/requirements.html) page documents how
+[Provider Requirements](/docs/language/providers/requirements.html)
-  to declare providers so Terraform can install them.
+page documents how to declare providers so Terraform can install them.
 
 ## Provider Configuration
 
@@ -182,7 +184,7 @@ from their parents.
 
 <a id="provider-versions"></a>
 
-## `version`: An Older Way to Manage Provider Versions
+## `version` (Deprecated)
 
 [inpage-versions]: #provider-versions
 
@@ -193,11 +195,6 @@ constraint in a provider configuration is only used if `required_providers`
 does not include one for that provider.
 
 **The `version` argument in provider configurations is deprecated.**
-In Terraform 0.13 and later, version constraints should always be declared in
+In Terraform 0.13 and later, always declare provider version constraints in
 [the `required_providers` block](/docs/language/providers/requirements.html). The `version`
 argument will be removed in a future version of Terraform.
-
--> **Note:** The `version` meta-argument made sense before Terraform 0.13, since
-Terraform could only install providers that were distributed by HashiCorp. Now
-that Terraform can install providers from multiple sources, it makes more sense
-to keep version constraints and provider source addresses together.

website/docs/language/providers/index.html.md

@@ -1,11 +1,18 @@
 ---
 layout: "language"
 page_title: "Providers - Configuration Language"
+description: |-
+  Terraform providers are plugins that allow Terraform to create resources and
+  use data sources from services, cloud providers, and other APIs. Read about
+  how to discover, install, and use providers.
 ---
 
 # Providers
 
-Terraform relies on plugins called "providers" to interact with remote systems.
+> **Hands-on:** Try the [Perform CRUD Operations with Providers](https://learn.hashicorp.com/tutorials/terraform/provider-use?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
+
+Terraform relies on plugins called "providers" to interact with cloud providers,
+SaaS providers, and other APIs. 
 
 Terraform configurations must declare which providers they require so that
 Terraform can install and use them. Additionally, some providers require

website/docs/language/providers/requirements.html.md

@@ -5,21 +5,22 @@ page_title: "Provider Requirements - Configuration Language"
 
 # Provider Requirements
 
+Terraform relies on plugins called "providers" to interact with remote systems.
+Terraform configurations must declare which providers they require, so that
+Terraform can install and use them. This page documents how to declare providers
+so Terraform can install them.
+
+> **Hands-on:** Try the [Perform CRUD Operations with Providers](https://learn.hashicorp.com/tutorials/terraform/provider-use) tutorial on HashiCorp Learn.
+
+Additionally, some providers require configuration (like endpoint URLs or cloud
+regions) before they can be used. The [Provider
+Configuration](/docs/language/providers/configuration.html) page documents how
+to configure settings for providers.
+
 -> **Note:** This page is about a feature of Terraform 0.13 and later; it also
 describes how to use the more limited version of that feature that was available
 in Terraform 0.12.
 
-Terraform relies on plugins called "providers" to interact with remote systems.
-
-Terraform configurations must declare which providers they require, so that
-Terraform can install and use them. Additionally, some providers require
-configuration (like endpoint URLs or cloud regions) before they can be used.
-
-- This page documents how to declare providers so Terraform can install them.
-
-- The [Provider Configuration](/docs/language/providers/configuration.html) page documents how to configure
-  settings for providers.
-
 ## Requiring Providers
 
 Each Terraform module must declare which providers it requires, so that
@@ -223,7 +224,7 @@ and commit it to version control along with your configuration. If a lock file
 is present, Terraform Cloud, CLI, and Enterprise will all obey it when
 installing providers.
 
-> **Hands-on:** Try the [Lock and Upgrade Provider Versions](https://learn.hashicorp.com/tutorials/terraform/provider-versioning?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
+> **Hands-on:** Try the [Lock and Upgrade Provider Versions](https://learn.hashicorp.com/tutorials/terraform/provider-versioning) tutorial on HashiCorp Learn.
 
 ### Best Practices for Provider Versions
 
@@ -289,7 +290,7 @@ compatible with Terraform v0.11 or later and should never be declared in a
 ## In-house Providers
 
 Anyone can develop and distribute their own Terraform providers. See
-the [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
+the [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers)
 collection on HashiCorp Learn for more
 about provider development.
 

website/docs/language/values/outputs.html.md

@@ -8,12 +8,15 @@ description: |-
 
 # Output Values
 
+Output values make information about your infrastructure available on the
+command line, and can expose information for other Terraform configurations to
+use. Output values are similar to return values in programming languages.
+
 > **Hands-on:** Try the [Output Data From
-Terraform](https://learn.hashicorp.com/tutorials/terraform/outputs?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
+Terraform](https://learn.hashicorp.com/tutorials/terraform/outputs)
 tutorial on HashiCorp Learn.
 
-Output values are like the return values of a Terraform module, and have several
+Output values have several uses:
-uses:
 
 - A child module can use outputs to expose a subset of its resource attributes
   to a parent module.

website/docs/language/values/variables.html.md

@@ -3,17 +3,18 @@ layout: "language"
 page_title: "Input Variables - Configuration Language"
 sidebar_current: "docs-config-variables"
 description: |-
-  Input variables are parameters for Terraform modules.
+  Input variables allow you to customize Terraform configuration according to 
-  This page covers configuration syntax for variables.
+  set parameters. Learn about input variable syntax, including how to declare,
+  define, and reference variables in root and child modules.
 ---
 
 # Input Variables
 
 > **Hands-on:** Try the [Customize Terraform Configuration with Variables](https://learn.hashicorp.com/tutorials/terraform/variables?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
 
-Input variables serve as parameters for a Terraform module, allowing aspects
+Input variables let you customize aspects of Terraform modules without altering
-of the module to be customized without altering the module's own source code,
+the module's own source code. This allows you to share modules across different
-and allowing modules to be shared between different configurations.
+Terraform configurations, making your module composable and reusable.
 
 When you declare variables in the root module of your configuration, you can
 set their values using CLI options and environment variables.

website/intro/index.html.markdown

@@ -17,6 +17,8 @@ If you are already familiar with the basics of Terraform, the
 [documentation](/docs/index.html) provides a better reference
 guide for all available features as well as internals.
 
+> **Hands-on:** Try the [Get Started](https://learn.hashicorp.com/tutorials/terraform/infrastructure-as-code) tutorials on HashiCorp Learn.
+
 ## What is Terraform?
 
 Terraform is a tool for building, changing, and versioning infrastructure
@@ -71,9 +73,9 @@ possible human errors.
 
 ## Next Steps
 
-See the page on [Terraform use cases](/intro/use-cases.html) to see the
+- Learn about common [Terraform use cases](/intro/use-cases.html) to find multiple
-multiple ways Terraform can be used. Then see
+ways you can use Terraform.
-[how Terraform compares to other software](/intro/vs/index.html)
+- Learn [how Terraform compares to other infrastructure tools](/intro/vs/index.html). 
-to see how it fits into your existing infrastructure. Finally, continue onwards with
+- Try the [Terraform: Get
-the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn to use
+  Started](https://learn.hashicorp.com/collections/terraform/aws-get-started)
-Terraform to manage real infrastructure and to see how it works.
+  tutorials on HashiCorp Learn to use Terraform to manage real infrastructure.