⭐ 🍌 Andrew Browns' Terraform Documentation Feedback Bonanza 🍌 ⭐

## Overture

I'm am auditing the entirety of the documentation for my free Terraform course and I have been collecting valuable information from DAs and HashiCorp Ambassadors which could and should go into the docs,


### Why aren't you creating induvial Issues?

I was going to open an issue for the technical documentation and it directed me to here, and I was surprised to see the technical documentation is tightly coupled to the primary repository and its not a separate repo. eg.

https://www.terraform.io/docs/language/index.html
https://www.terraform.io/docs/cli/index.html

As a person who wants to contribute to the technical documentation this makes it much more difficult because I have to swim in a sea of unrelated issues and pull requests.

There isn't a Issue type for contributing to the docs and ideally you'd want multiple issues types.

What other providers do like AWS, Azure and GCP is have a stand alone repo and they will live in their own Github Organization:
https://github.com/awsdocs

## Issues

### General Advice

- [ ] move documentation to its own Github Organization eg. terraformdocs and have docs reside their their own repos
- [ ] remove foo/bar examples and replace with examples that emulate real world scenarios.
- [x] Hire a technical writer
- [ ] all sections should have an overview eg. Generic Provisioners, Meta-Arguments, Vendor Provisioners eg. Overview
- [ ] defining an architectural icon set would be very useful. For example there is no unique icon for Sentinel or Terraform Cloud Run Environment.
- [ ] make the edit button more obvious for contributors within the docs. Preferably in the top right corner, similar to various CSPs documentation

### Don't know where they go but they should in the docs

- [ ] add a page on GitOps and Terraform workflows for GitOps,
- [ ] Configuration Drift appears missing in the documentation,
- [ ] Solutions for achieving immutable infrastructure
- [ ] The fine line between a provisioner like Postgres against IaC and Configuration Management
- [ ] provide developer or business use cases.
- [ ] Terraform Cloud, use case for manually running terraform plan within a workspace. Describe different business workflows

### Terraform Language

- [ ] Rename Generic Provisioners to Executioners, give them top level in the documentation tree
https://www.terraform.io/docs/language/resources/provisioners/remote-exec.html
- [ ] Should mention HCL and how Terraform Language relates to HCL https://www.terraform.io/docs/language/index.html#about-the-terraform-language
- [ ] local-exec - give examples of local exec environments eg. Local Machine, Build Server, Terraform Cloud Run Environment and example use cases of why local-exec would be used. I was told its generally in configuration management workflows, but that is not the examples shown.
- [ ] remote-exec - show a diagram of remote exec to cement where execution is happening, provide an example for a Windows and Linux Machines
- [ ] remote-exec - show examples of script and scripts, Its not clear how execution would work. With local-exec can you provide an interpreter.
- [ ] Ansible and Terraform - Ansible is not mentioned under Provisioners, Terraform has been presented to compliment Ansible, I think a page in the Language Docs should include a page on Ansible.
- [ ] Provisioners suggest to learn towards using Packer, provide a simple example in this section with Terraform + Packer and the three CSPs
- [ ] Terraform Providers - better describe the relation of a Provider to an CSPS API, is it a one-to-one mapping or does Terraform do a bit more?
- [ ] Terraform Module - provide a clear example of the benefit of modules ( a good side by side would be an Azure VM via the Provider vs a Module)
- local values - compare it against Input Variables, why would I not want to use Input Variables and instead using Locals Values?
### Terraform CLI

- [ ] terraform get - provide an example use case when it would be used.
- [ ] terraform taint - explain using a developer workflow the purpose of having to use taint previously and how the new workflow would work. There is kind of example but its not clear
- [ ] terraform validate - explain what it will not do. For example if you provide an invalid AWS ami it will not know that its invalid, because its checking that its string not that the content is valid
- [ ] Resource Addressing - show examples that uses modules when using resource addressing, it only shows for a resource without modules.
- [ ] terraform plan - it could use a TL;DR at the top. "Terraform plan allows you to see a dry run by generating out an execution plan so you can manually review will be added, changed or destroyed."
- [ ] For Terraform State its not clear if there can be multiple backup files or if its just a single backup file. https://www.terraform.io/docs/cli/commands/state/index.html#backups

Start with the linked Terraform Language and CLI documentation, especially the Provisioners, Terraform Language, and State sections. The issue combines repository organization, navigation, examples, diagrams, workflows, and many documentation topics; it would need to be split into scoped issues before a contributor could identify a file, test, or clear definition of done.

Written by the indexing model from the issue text.