diff --git a/docs/authoriing.md b/docs/authoriing.md
new file mode 100644
index 000000000..40c3d6f11
--- /dev/null
+++ b/docs/authoriing.md
@@ -0,0 +1,37 @@
+# kustomization authoring
+
+kustomize provides sub-commands for managing the contents of a kustomization file from the command line.
+
+## kustomize create
+
+The `kustomize create` command will create a new kustomization in the current directory.
+
+When run without any flags the command will create an empty `kustomization.yaml` file that can then be updated manually or with the `kustomize edit` sub-commands.
+
+```
+kustomize create --namespace=myapp --resources=deployment.yaml,service.yaml --label=app=myapp
+```
+
+### Detecting resources
+
+> NOTE: Resource detection will not follow symlinks.
+
+Flags:
+      --annotation string   Add one or more common annotations.
+      --autodetect          Search for kubernetes resources in the current directory to be added to the kustomization file.
+  -h, --help                help for create
+      --label string        Add one or more common labels.
+      --nameprefix string   Sets the value of the namePrefix field in the kustomization file.
+      --namespace string    Set the value of the namespace field in the customization file.
+      --namesuffix string   Sets the value of the nameSuffix field in the kustomization file.
+      --recursive           Enable recursive directory searching for resource auto-detection.
+      --resources string    Name of a file containing a file to add to the kustomization file.
+
+## kustomize edit
+
+With an existing kustomization file the `kustomize edit` command 
+
+* add
+* set
+* remove
+* fix
\ No newline at end of file
diff --git a/docs/plugins/README.md b/docs/plugins/README.md
index f250da22b..90b972f03 100644
--- a/docs/plugins/README.md
+++ b/docs/plugins/README.md
@@ -244,6 +244,46 @@ kustomize uses an exec plugin adapter to provide
 marshalled resources on `stdin` and capture
 `stdout` for further processing.
 
+#### Generator Options
+
+A generator exec plugin can adjust the generator options for the resources it emits by setting one of the following internal annotations. 
+
+> NOTE: These annotations are local to kustomize and will not be included in the final output.
+
+**`kustomize.config.k8s.io/needs-hash`**
+
+Resources can be marked as needing to be processed by the internal hash transformer by including the `needs-hash` annotation. When set valid values for the annotation are `"true"` and `"false"` which respectively enable or disable hash suffixing for the resource. Omitting the annotation is equivalent to setting the value `"false"`.
+
+If this annotation is set on a resource not supported by the hash transformer the build will fail.
+
+Example:
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm-test
+  annotations:
+    kustomize.config.k8s.io/needs-hash: "true"
+data:
+  foo: bar   
+```
+
+**`kustomize.config.k8s.io/behavior`**
+
+The `behavior` annotation will influence how conflicts are handled for resources emitted by the plugin. Valid values include "create", "merge", and "replace" with "create" being the default. 
+
+Example:
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: cm-test
+  annotations:
+    kustomize.config.k8s.io/behavior: "merge"
+data:
+  foo: bar   
+```
+
 ### Go plugins
 
 Be sure to read [Go plugin caveats](goPluginCaveats.md).