Merge pull request #29051 from hashicorp/add-page-metadata

Add page metadata

website/guides/core-workflow.html.md

@@ -3,9 +3,7 @@ layout: "intro"
 page_title: "The Core Terraform Workflow - Guides"
 sidebar_current: "guides-core-workflow"
 description: |-
-  This guide provides an overview of the core Terraform workflow and how it
-  applies in individual, team, and organization contexts across Terraform open
-  source and Terraform Cloud.
+  An overview of how individuals, teams, and organizations can use Terraform. 
 ---
 
 # The Core Terraform Workflow

website/intro/index.html.markdown

@@ -3,79 +3,41 @@ layout: "intro"
 page_title: "Introduction"
 sidebar_current: "what"
 description: |-
-  Welcome to the intro guide to Terraform! This guide is the best place to start with Terraform. We cover what Terraform is, what problems it can solve, how it compares to existing software, and contains a quick start for using Terraform.
+  Learn what Terraform is, what problems it can solve, and how it compares to existing software.
 ---
 
 # Introduction to Terraform
 
-Welcome to the intro guide to Terraform! This guide is the best
-place to start with Terraform. We cover what Terraform is, what
-problems it can solve, how it compares to existing software,
-and contains a quick start for using Terraform.
+Terraform is an infrastructure as code (IaC) tool that allows you to build, change, and version infrastructure safely and efficiently. This includes low-level components such as compute instances, storage, and networking, as well as high-level components such as DNS entries, SaaS features, etc. Terraform can manage both existing service providers and custom in-house solutions.
 
-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
-safely and efficiently. Terraform can manage existing and popular service
-providers as well as custom in-house solutions.
-
-Configuration files describe to Terraform the components needed to
-run a single application or your entire datacenter.
-Terraform generates an execution plan describing
-what it will do to reach the desired state, and then executes it to build the
-described infrastructure. As the configuration changes, Terraform is able
-to determine what changed and create incremental execution plans which
-can be applied.
-
-The infrastructure Terraform can manage includes
-low-level components such as
-compute instances, storage, and networking, as well as high-level
-components such as DNS entries, SaaS features, etc.
+Below, HashiCorp co-founder and CTO Armon Dadgar describes how Terraform can help solve common infrastructure challenges.
 
 <iframe src="https://www.youtube.com/embed/h970ZBgKINg" frameborder="0" allowfullscreen="true"  width="560" height="315" ></iframe>
 
-Examples work best to showcase Terraform. Please see the
-[use cases](/intro/use-cases.html).
 
-The key features of Terraform are:
+
+## Key Features
 
 ### Infrastructure as Code
 
-Infrastructure is described using a high-level configuration syntax. This allows
-a blueprint of your datacenter to be versioned and treated as you would any
-other code. Additionally, infrastructure can be shared and re-used.
+You describe your infrastructure using Terraform's high-level [configuration language](/docs/language/index.html) in human-readable, declarative configuration files. This allows you to create a blueprint that you can version, share, and reuse.
 
 ### Execution Plans
 
-Terraform has a "planning" step where it generates an _execution plan_. The
-execution plan shows what Terraform will do when you call apply. This lets you
-avoid any surprises when Terraform manipulates infrastructure.
+Terraform generates an _execution plan_ describing what it will do and asks for your approval before making any infrastructure changes. This allows you to review changes before Terraform creates, updates, or destroys infrastructure.
 
 ### Resource Graph
 
-Terraform builds a graph of all your resources, and parallelizes the creation
-and modification of any non-dependent resources. Because of this, Terraform
-builds infrastructure as efficiently as possible, and operators get insight into
-dependencies in their infrastructure.
+Terraform builds a resource graph and creates or modifies non-dependent resources in parallel. This allows Terraform to build resources as efficiently as possible and gives you greater insight into your infrastructure.
 
 ### Change Automation
 
-Complex changesets can be applied to your infrastructure with minimal human
-interaction. With the previously mentioned execution plan and resource graph,
-you know exactly what Terraform will change and in what order, avoiding many
-possible human errors.
+Terraform can apply complex changesets to your infrastructure with minimal human interaction. When you update configuration files, Terraform determines what changed and creates incremental execution plans that respect dependencies.
+
+
 
 ## Next Steps
 
-- Learn about common [Terraform use cases](/intro/use-cases.html) to find multiple
-ways you can use Terraform.
-- Learn [how Terraform compares to other infrastructure tools](/intro/vs/index.html). 
-- Try the [Terraform: Get
-  Started](https://learn.hashicorp.com/collections/terraform/aws-get-started)
-  tutorials on HashiCorp Learn to use Terraform to manage real infrastructure.
+- Learn about common [Terraform use cases](/intro/use-cases.html).
+- Learn [how Terraform compares to and complements other tools](/intro/vs/index.html).
+- Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started) tutorials on HashiCorp Learn.

website/intro/use-cases.html.markdown

@@ -3,28 +3,18 @@ layout: "intro"
 page_title: "Use Cases"
 sidebar_current: "use-cases"
 description: |-
-  Before understanding use cases, it's useful to know what Terraform is. This page lists some concrete use cases for Terraform, but the possible use cases are much broader than what we cover. Due to its extensible nature, providers and provisioners can be added to further extend Terraform's ability to manipulate resources.
+  Learn common use cases for Terraform including managing Heroku apps, self-service clusters, and multi-cloud deployments.
 ---
 
 # Use Cases
 
-Before understanding use cases, it's useful to know [what Terraform is](/intro/index.html).
-This page lists some concrete use cases for Terraform, but the possible use cases are
-much broader than what we cover. Due to its extensible nature, providers and provisioners
-can be added to further extend Terraform's ability to manipulate resources.
+This page lists a subset of use cases for [Terraform](/intro/index.html).
 
 ## Heroku App Setup
 
-Heroku is a popular PaaS for hosting web apps. Developers create an app, and then
-attach add-ons, such as a database, or email provider. One of the best features is
-the ability to elastically scale the number of dynos or workers. However, most
-non-trivial applications quickly need many add-ons and external services.
+Heroku is a popular PaaS for hosting web apps. Developers create an app, and then attach add-ons, such as a database, or email provider. One of the best features is the ability to elastically scale the number of dynos or workers. However, most non-trivial applications quickly need many add-ons and external services.
 
-Terraform can be used to codify the setup required for a Heroku application, ensuring
-that all the required add-ons are available, but it can go even further: configuring
-DNSimple to set a CNAME, or setting up Cloudflare as a CDN for the
-app. Best of all, Terraform can do all of this in under 30 seconds without
-using a web interface.
+You can use Terraform to codify the setup required for a Heroku application, ensuring that all the required add-ons are available, but it can go even further: configuring DNSimple to set a CNAME, or setting up Cloudflare as a CDN for the app. Best of all, Terraform can do all of this in under 30 seconds without using a web interface.
 
 ## Multi-Tier Applications
 
@@ -33,12 +23,7 @@ a pool of web servers that use a database tier. Additional tiers get added for A
 caching servers, routing meshes, etc. This pattern is used because the tiers can be scaled
 independently and provide a separation of concerns.
 
-Terraform is an ideal tool for building and managing these infrastructures. Each tier can
-be described as a collection of resources, and the dependencies between each tier are handled
-automatically; Terraform will ensure the database tier is available before the web servers
-are started and that the load balancers are aware of the web nodes. Each tier can then be
-scaled easily using Terraform by modifying a single `count` configuration value. Because
-the creation and provisioning of a resource is codified and automated, elastically scaling
+Terraform is an ideal tool for building and managing these infrastructures. You can group resources in each tier together, and Terraform will automatically handle the dependencies between each tier. For example, Terraform will ensure the database tier is available before provisioning the web servers and that the load balancers are connected to the web nodes. You can then use Terraform to easily scale each tier by modifying the `count` configuration value. Because resource creation and provisioning is codified and automated, elastically scaling
 with load becomes trivial.
 
 ## Self-Service Clusters
@@ -48,10 +33,7 @@ operations team to manage a large and growing infrastructure. Instead it becomes
 more attractive to make "self-serve" infrastructure, allowing product teams to
 manage their own infrastructure using tooling provided by the central operations team.
 
-Using Terraform, the knowledge of how to build and scale a service can be codified
-in a configuration. Terraform configurations can be shared within an organization
-enabling customer teams to use the configuration as a black box and use Terraform as
-a tool to manage their services.
+You can use Terraform configuration to codify the knowledge of how to build and scale a service. You can then share these configurations throughout your organization, enabling customer teams to use Terraform to manage their services.
 
 ## Software Demos
 
@@ -61,9 +43,7 @@ for demos, it is still very challenging to demo software on real infrastructure
 which more closely matches production environments.
 
 Software writers can provide a Terraform configuration to create, provision and
-bootstrap a demo on cloud providers like AWS. This allows end users to easily demo
-the software on their own infrastructure, and even enables tweaking parameters like
-cluster size to more rigorously test tools at any scale.
+bootstrap a demo on cloud providers like AWS. This allows end users to easily demo the software on their own infrastructure, and even enables tweaking parameters like cluster size to more rigorously test tools at any scale.
 
 ## Disposable Environments
 
@@ -86,12 +66,9 @@ datacenter, as it provides more control to operators and developers and
 allows the network to better support the applications running on top. Most SDN
 implementations have a control layer and infrastructure layer.
 
-Terraform can be used to codify the configuration for software defined networks.
-This configuration can then be used by Terraform to automatically setup and modify
-settings by interfacing with the control layer. This allows configuration to be
-versioned and changes to be automated. As an example, [AWS VPC](https://aws.amazon.com/vpc/)
-is one of the most commonly used SDN implementations, and [can be configured by
-Terraform](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc).
+You can use Terraform to codify the configuration for software defined networks.
+Terraform can then use this configuration to automatically set up and modify settings by interfacing with the control layer. This allows the configuration to be
+versioned and changes to be automated. For example, you can [use Terraform to configure AWS VPC](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/vpc).
 
 ## Resource Schedulers
 
@@ -108,13 +85,9 @@ running the schedulers as well as provisioning onto the scheduled grid.
 
 ## Multi-Cloud Deployment
 
-It's often attractive to spread infrastructure across multiple clouds to increase
-fault-tolerance. By using only a single region or cloud provider, fault tolerance
-is limited by the availability of that provider. Having a multi-cloud deployment
-allows for more graceful recovery of the loss of a region or entire provider.
+It's often attractive to spread infrastructure across multiple clouds to increase fault-tolerance. By using only a single region or cloud provider, fault tolerance is limited by the availability of that provider. Multi-cloud deployment allows for more graceful recovery of the loss of a region or entire provider.
 
 Realizing multi-cloud deployments can be very challenging as many existing tools
 for infrastructure management are cloud-specific. Terraform is cloud-agnostic
 and allows a single configuration to be used to manage multiple providers, and
-to even handle cross-cloud dependencies. This simplifies management and orchestration,
-helping operators build large-scale multi-cloud infrastructures.
+to even handle cross-cloud dependencies. This simplifies management and orchestration, helping operators build large-scale multi-cloud infrastructures.

website/intro/vs/boto.html.markdown

@@ -3,7 +3,7 @@ layout: "intro"
 page_title: "Terraform vs. Boto, Fog, etc."
 sidebar_current: "vs-other-boto"
 description: |-
-  Libraries like Boto, Fog, etc. are used to provide native access to cloud providers and services by using their APIs. Some libraries are focused on specific clouds, while others attempt to bridge them all and mask the semantic differences. Using a client library only provides low-level access to APIs, requiring application developers to create their own tooling to build and manage their infrastructure.
+  How Terraform compares to cloud provider client libraries like Boto and Fog. 
 ---
 
 # Terraform vs. Boto, Fog, etc.
@@ -21,4 +21,3 @@ how cloud resources and services should be created, provisioned, and
 combined. Terraform is very flexible, using a plugin-based model to
 support providers and provisioners, giving it the ability to support
 almost any service that exposes APIs.
-

website/intro/vs/chef-puppet.html.markdown

@@ -3,7 +3,7 @@ layout: "intro"
 page_title: "Terraform vs. Chef, Puppet, etc."
 sidebar_current: "vs-other-chef"
 description: |-
-  Configuration management tools install and manage software on a machine that already exists. Terraform is not a configuration management tool, and it allows existing tooling to focus on their strengths: bootstrapping and initializing resources.
+    How Terraform compares to configuration management tools like Chef and Puppet. 
 ---
 
 # Terraform vs. Chef, Puppet, etc.
@@ -22,4 +22,3 @@ If you are using traditional configuration management within your compute
 instances, you can use Terraform to configure bootstrapping software like
 cloud-init to activate your configuration management software on first
 system boot.
-

website/intro/vs/cloudformation.html.markdown

@@ -3,7 +3,7 @@ layout: "intro"
 page_title: "Terraform vs. CloudFormation, Heat, etc."
 sidebar_current: "vs-other-cloudformation"
 description: |-
-  Tools like CloudFormation, Heat, etc. allow the details of an infrastructure to be codified into a configuration file. The configuration files allow the infrastructure to be elastically created, modified and destroyed. Terraform is inspired by the problems they solve.
+  How Terraform compares to other infrastructure as code tools like CloudFormation and Heat. Terraform can simultaneously manage multiple cloud providers (AWS, OpenStack, etc.) and services (Cloudflare, DNSimple, etc.).
 ---
 
 # Terraform vs. CloudFormation, Heat, etc.

website/intro/vs/custom.html.markdown

@@ -3,7 +3,7 @@ layout: "intro"
 page_title: "Terraform vs. Custom Solutions"
 sidebar_current: "vs-other-custom"
 description: |-
-  Most organizations start by manually managing infrastructure through simple scripts or web-based interfaces. As the infrastructure grows, any manual approach to management becomes both error-prone and tedious, and many organizations begin to home-roll tooling to help automate the mechanical processes involved.
+ Why Terraform is easier to use and maintain than custom, internal infrastructure solutions.
 ---
 
 # Terraform vs. Custom Solutions
@@ -37,4 +37,3 @@ fix bugs and document new use cases. Terraform helps solve a problem
 that exists in every organization and provides a standard that can
 be adopted to avoid reinventing the wheel between and within organizations.
 Its open source nature ensures it will be around in the long term.
-

website/intro/vs/index.html.markdown

@@ -3,7 +3,7 @@ layout: "intro"
 page_title: "Terraform vs. Other Software"
 sidebar_current: "vs-other"
 description: |-
-  Terraform provides a flexible abstraction of resources and providers. This model allows for representing everything from physical hardware, virtual machines, and containers, to email and DNS providers. Because of this flexibility, Terraform can be used to solve many different problems. This means there are a number of existing tools that overlap with the capabilities of Terraform. We compare Terraform to a number of these tools, but it should be noted that Terraform is not mutually exclusive with other systems. It can be used to manage a single application, or the entire datacenter.
+  An overview of how Terraform compares to other software and tools.
 ---
 
 # Terraform vs. Other Software