Terraform: Terraform documentation needs improvement

[KbLev]

All of the pages give you just the bare minimum information about everything. The most basic examples. If you want more info you have to dig github and try to find code samples there.

For example I was trying to see how to consume outputs from modules.
Just a one liner example on the definition. But no example on how to use the output somewhere else.

Then, I wanted to see how to do lookups.
There's not one example on lookups, at least not on the interpolations page. All functions should have their own dedicated page with a few examples at least.

The resources list one example, and usually the basic ones. And exported values are not included, though this would be really informational. For example an _azurerm_virtual_network_gateway_ can be of type VPN and ExpressRoute with very different configuration. It was nice to have two samples.

The entire Terraform documentation screams "let's just complete this with the least possible effort". Hey, less potential for errors and less updating later.

[JarredAxsen]

I also agree on the points made above.

I will also point out under larger providers like AWS it is truly annoying to have to scroll for hours to get to the correct link on the left hand side.

Can you please create drop downs in the navigation?

[cstuart1]

Terraform is great ... but the documentation is subpar.
In fact, it remindes me of writing a conditional in Terraform which reminds me of something like this --

count = "${something == "" ? 1 : 0} # Umm, okay..
"${something != "" ? something : join("", aws_security_group.default_sg.*.id)}" # Lol, seriously.

Terraform .12 is supposed to address some of these issues and I hope the same can be said for the accompanying documenation!

[paultyng]

I'll respond to your issues, but before that, we expect kind discourse. We accept criticism and are happy to respond, but criticism can be delivered constructively without expletives and what may feel like attacks.

Some of these things are being address in 0.12. For example, functions are each getting their own page, here is an example for lookup.

The AWS navigation is definitely something we realize is an issue, the provider has grown so quickly we haven't had an opportunity to revisit the navigation to improve its usability (most of us are backend / Go engineers, so UI improvements aren't as easy to do) but its definitely something we realize is an issue and are trying to find a better solution.

If specific providers or resources are missing examples you would like, the provider repositories and documentation are separate from Terraform's core repository (and not always maintained by HashiCorp, although both the mentioned AWS and AzureRM providers are). You can open issues on those repositories or submit PRs to their website files directly:

• https://github.com/terraform-providers/terraform-provider-aws
• https://github.com/terraform-providers/terraform-provider-azurerm

[apparentlymart]

As Paul said, documentation is an ongoing effort and we will continue to improve it alongside development work.

Since this issue does not represent a discrete, actionable piece of work I'm going to close it out. This isn't meant to imply that there isn't work to do here, but that "the documentation needs to be improved" is not something that could ever be "complete" as stated. If there is specific feedback you'd like to give that isn't already covered by an issue, please do feel free to open issues or PRs in either this repository (for the general Terraform documentation) or in the provider repositories (for provider-specific documentation) and those changes will be prioritized along with other work.

Thanks!

[hashibot[bot]]

I'm going to lock this issue because it has been closed for _30 days_ ⏳. This helps our maintainers find and focus on the active issues.

If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.