diff --git a/website/source/docs/providers/local/index.html.markdown b/website/source/docs/providers/local/index.html.markdown
index cc83fd241..8c007c15a 100644
--- a/website/source/docs/providers/local/index.html.markdown
+++ b/website/source/docs/providers/local/index.html.markdown
@@ -3,17 +3,18 @@ layout: "local"
 page_title: "Provider: Local"
 sidebar_current: "docs-local-index"
 description: |-
-  The Local provider is used to manage local resources (i.e. files).
+  The Local provider is used to manage local resources, such as files.
 ---
 
 # Local Provider
 
-The Local provider is used to manage local resources (i.e. files).
+The Local provider is used to manage local resources, such as files.
 
 Use the navigation to the left to read about the available resources.
 
-## Example Usage
-
-```
-provider "local" {}
-```
+~> **Note** Terraform primarily deals with remote resources which are able
+to outlive a single Terraform run, and so local resources can sometimes violate
+its assumptions. The resources here are best used with care, since depending
+on local state can make it hard to apply the same Terraform configuration on
+many different local systems where the local resources may not be universally
+available. See specific notes in each resource for more information.
diff --git a/website/source/docs/providers/local/r/file.html.md b/website/source/docs/providers/local/r/file.html.md
index f0e3c8628..83ac2a325 100644
--- a/website/source/docs/providers/local/r/file.html.md
+++ b/website/source/docs/providers/local/r/file.html.md
@@ -6,14 +6,20 @@ description: |-
   Generates a local file from content.
 ---
 
-# local\_file
+# local_file
 
-Generates a local file from a given content.
+Generates a local file with the given content.
+
+~> **Note** When working with local files, Terraform will detect the resource
+as having been deleted each time a configuration is applied on a new machine
+where the file is not present and will generate a diff to re-create it. This
+may cause "noise" in diffs in environments where configurations are routinely
+applied by many different users or within automation systems.
 
 ## Example Usage
 
-```
-data "local_file" "foo" {
+```hcl
+resource "local_file" "foo" {
     content     = "foo!"
     filename = "${path.module}/foo.bar"
 }
@@ -23,8 +29,9 @@ data "local_file" "foo" {
 
 The following arguments are supported:
 
-* `content` - (required) The content of file to create.
+* `content` - (Required) The content of file to create.
 
-* `filename` - (required) The path of the file to create.
+* `filename` - (Required) The path of the file to create.
 
-NOTE: Any required parent folders are created automatically. Additionally, any existing file will get overwritten.
\ No newline at end of file
+Any required parent directories will be created automatically, and any existing
+file with the given name will be overwritten.