website: Revise the "Local Values" configuration docs section

This adopts a more guide-like writing style, similar to what prior commits
have done to some other subsections of this section.

website/docs/configuration/locals.html.md

@@ -7,86 +7,72 @@ description: |-
   within a module.
 ---
 
-# Local Value Configuration
+# Local Values
 
-Local values assign a name to an expression, that can then be used multiple
-times within a module.
+A local value assigns a name to an [expression](/docs/configuration/expressions.html),
+allowing it to then be used multiple times within a module without repeating
+it.
 
 Comparing modules to functions in a traditional programming language,
-if [variables](./variables.html) are analogous to function arguments and
-[outputs](./outputs.html) are analogous to function return values then
-_local values_ are comparable to a function's local variables.
+if [input variables](./variables.html) are analogous to function arguments and
+[outputs values](./outputs.html) are analogous to function return values then
+_local values_ are comparable to a function's local temporary symbols.
 
-This page assumes you're already familiar with
-[the configuration syntax](/docs/configuration/syntax.html).
+## Declaring a Local Value
 
-## Examples
-
-Local values are defined in `locals` blocks:
+A set of related local values can be delared together in a single `locals`
+block:
 
 ```hcl
-# Ids for multiple sets of EC2 instances, merged together
-locals {
-  instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
-}
-
-# A computed default name prefix
 locals {
-  default_name_prefix = "${var.project_name}-web"
-  name_prefix         = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
-}
-
-# Local values can be interpolated elsewhere using the "local." prefix.
-resource "aws_s3_bucket" "files" {
-  bucket = "${local.name_prefix}-files"
-  # ...
+  service_name = "forum"
+  owner        = "Community Team"
 }
 ```
 
-Named local maps can be merged with local maps to implement common or default
-values:
+For brevity, local values are often referred to just as "locals", when the
+meaning is clear from context.
+
+The expressions assigned to local value names can either be simple constants
+like the above, allowing these values to be defined only once but used many
+times, or they can be more complex expressions that transform or combine
+values from elsewhere in the module:
 
 ```hcl
-# Define the common tags for all resources
 locals {
-  common_tags = {
-    Component   = "awesome-app"
-    Environment = "production"
-  }
+  # Ids for multiple sets of EC2 instances, merged together
+  instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
 }
 
-# Create a resource that blends the common tags with instance-specific tags.
-resource "aws_instance" "server" {
-  ami           = "ami-123456"
-  instance_type = "t2.micro"
-
-  tags = "${merge(
-    local.common_tags,
-    map(
-      "Name", "awesome-app-server",
-      "Role", "server"
-    )
-  )}"
+locals {
+  # Common tags to be assigned to all resources
+  common_tags = {
+    Service = local.service_name
+    Owner   = local.owner
+  }
 }
 ```
 
-## Description
+As shown above, local values can be referenced from elsewhere in the module
+with an expression like `local.common_tags`, and output values can reference
+each other in order to build more complex values from simpler ones.
 
-The `locals` block defines one or more local variables within a module.
-Each `locals` block can have as many locals as needed, and there can be any
-number of `locals` blocks within a module.
+```
+resource "aws_instance" "example" {
+  # ...
+
+  tags = local.common_tags
+}
+```
 
-The names given for the items in the `locals` block must be unique throughout
-a module. The given value can be any expression that is valid within
-the current module.
+## When To Use Local Values
 
-The expression of a local value can refer to other locals, but as usual
-reference cycles are not allowed. That is, a local cannot refer to itself
-or to a variable that refers (directly or indirectly) back to it.
+Local Values can be helpful to avoid repeating the same values or expressions
+multiple times in a configuration, but if overused they can also make a
+configuration hard to read by future maintainers by hiding the actual values
+used.
 
-It's recommended to group together logically-related local values into
-a single block, particularly if they depend on each other. This will help
-the reader understand the relationships between variables. Conversely,
-prefer to define _unrelated_ local values in _separate_ blocks, and consider
-annotating each block with a comment describing any context common to all
-of the enclosed locals.
+Use Local Values only in moderation, in situations where a single value or
+result is used in many places _and_ that value is likely to be changed in
+future. The ability to easily change the value in a central place is the key
+advantage of local values.