Docs are difficult + incomplete

Generally, overall documentation on Terraform is above industry standards, and it has been extremely useful. That being said, I have had issues, where the documentation is incomplete. In some providers, so you have to go outside of Terraform (explore the cloud rest api, source code, etc). This happens a lot of nested blocks that has sparse documentation.

One issue I came up is using dynamic blocks with nested structures (ref).

What was subtle and not clear, is that script blocks or maps have to be in an one element set. I don’t know if this is some sort of thing to pass something by reference, but it was not clear. What would have helped would be to have the variable definition as an example, then it would be more clear, and/or documenting why we need to have a one-element set or list to be able to use the data structures we create with dynamic blocks.

Also not clear, was that if part of the block items are not use, you can use null, or if it is a nested dynamic block you would set this to an empty list []. The final result will be the item is omitted.

My use case is managing DNS records using Terraform. This will come up when using Cloudflare, Google Cloud DNS, AWS Route 53, Azure DNS, etc. Creating static resources for DNS records is not feasible, so having a easy to use list that is used by an indexed resource is far easier to maintain.

Other similar scenarios, such as any time you have 20+ records that are similar, and you would prefer to have one resource block to enumerate a list and create the resources.

Anyhow, I hope this is received, useful, and helps make the documentation better.