helper/schema: Adjusted validation error messages

[apparentlymart]

Some of the validation error messages were written with the provider developer audience rather than the end-user audience in mind, and so in helping various folks in the community forum, etc I've occasionally seen folks be confused as to what these messages mean and what to do about them.

The main cases I came here to address were:

• The error messages whose summaries directly mention field names from the schema.Schema type, which is not something we expect end-sers to be familiar with.
• The "computed attributes cannot be set" error, because the terminology "computed" doesn't appear in our user-facing documentation. Since we don't actually really have a specific and consistent term for that, rather than introducing one here I instead made it a more plain description of the situation: an "unconfigurable attribute".

Since I was here anyway I also did some general review of the terminology used and adjusted some things that were not necessarily confusing but that were using different terminology than Terraform Core would use for a similar problem. However, for many of them I didn't change them heavily because in many cases these validation errors are masked by equivalent schema-based validation in Terraform Core itself anyway, and so these can often be seen only by Terraform v0.10/v0.11 users.

[paddycarver]

I'm noticing some inconsistencies here about when "attribute" is used and when "argument" is used. Is there an underlying system at work here that I'm not picking up on?

[paddycarver]

This may not be strictly correct, as I believe this would error if none of the arguments were selected, or if more than one of the arguments were selected.

Suggested change

	Summary: "Missing required argument",
	Summary: "Invalid number of arguments",

[apparentlymart]

Ahh yes, true: this can actually be describing two different problems:

• You didn't set any of the arguments in the set.
• You set more than one of the arguments in the set.

I think I'd prefer to change this to "Invalid combination of arguments", because "number" here makes it feel to me like there's the wrong number of arguments in this block in total, rather than the wrong number of arguments within this particular set of arguments that isn't directly visible to the user except in this error message. I will change it, though!

[apparentlymart]

Regarding argument vs. attribute: "attribute" is the general term for something you could access on the resulting object using attribute syntax, like .foo, whereas "argument" describes the subset of attributes that you can set in the configuration.

We adopted this terminology in response to the large amount of existing precedent in provider documentation, like in aws_instance where we have the heading "Argument Reference" talking about what users can set and the heading "Attributes Reference" which defines various other attributes "in addition to all arguments above". This terminology is now reflected in the main Terraform Language documentation, in Resource Arguments and in Accessing Resource Attributes.

This also speaks a bit to my comment about referring to the "unconfigurable attributes" in my initial writeup: we don't have any established terminology in the user model for what's left if you subtract "arguments" from "attributes", and so I coined "unconfigurable attributes" here as an informal way to refer to those.

[paddycarver]

Thanks @apparentlymart, I think this is much clearer for users and I'm happy to see the consistency in terms get propagated :)

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.