Update resources to be in line with current patterns #82
Conversation
roaks3
changed the title
| @@ -22,7 +22,7 @@ var peeringDeleteTimeout = time.Minute * 35 | |||
|
|
|||
| func resourceAwsNetworkPeering() *schema.Resource { | |||
| return &schema.Resource{ | |||
| Description: "The AWS Network peering resource allows you to manage a Network peering between an HVN and a peer AWS VPC.", | |||
| Description: "The AWS Network Peering resource allows you to manage a network peering between an HVN and a peer AWS VPC.", | |||
There was a problem hiding this comment.
The first Network Peering should be lowercased too. Same with the data source (and import maybe?).
I also noticed this in the Transit Gateway Attachment docs.
There was a problem hiding this comment.
Ah yea, this actually came up before for the transit gateway resources and I got the following guidance from Josh: #58 (comment)
In short, because there is a leading AWS, the entire noun gets title-cased. I'm not sure if the guidance has changed, but if not I think this is correct as-is.
There was a problem hiding this comment.
Ooh I see 🤔 We might need to fix up some of the consul resources then, they seemed to stick with sentence case even in the descriptions (https://github.com/hashicorp/terraform-provider-hcp/blob/main/internal/provider/resource_consul_cluster.go#L57).
There was a problem hiding this comment.
Oh boy, we've definitely found some edge cases with these 😄
@joshklekamp can you verify that we still have this right? The following line that @bcmdarroch linked seems like it would be incorrect, and we would want to capitalize the second cluster:
The Consul cluster resource allows you to manage an HCP Consul cluster.
There was a problem hiding this comment.
I don't believe we capitalize cluster, only branded features. I'm not familiar with the term "AWS Network Peering resource" though. If it's a feature of AWS's, I say keep it capitalized, but if not, we might want to revise to "AWS network peering resource".
There was a problem hiding this comment.
According to this comment:
- Top-level descriptions are all capitalized:
AWS Transit Gateway Attachment, AWS Network Peering, Consul Cluster( only TGW does this currently, in the first paragraph) - Everywhere else is sentence-cased:
AWS transit gateway attachment, AWS network peering, Consul cluster
We can definitely go forward with that, and I'll add a ticket for getting consistency across the resources.
But this does have me wondering if the top-level description exception is worth having, since it just ends up in the first paragraph, not a heading or title. 🤔
Also to throw in another wrench, it looks like AWS capitalizes Transit Gateways and lower-cases peering. So do we add a rule that respects the casing of the brand for certain resources?
There was a problem hiding this comment.
It might be helpful to pull in Kaitlin here. I tend to differ to her since design tries to align to the Learn team's writing style. I think the examples you provided @bcmdarroch might need a little revision. I think design's POV would be that:
- Product-specific features are all capitalized:
AWS Transit Gateway Attachment, AWS Peering Connection - Everywhere else is sentence-cased: transit gateway attachment, network peering, , peering connection, Consul cluster
There was a problem hiding this comment.
@joshklekamp thanks for checking in here! What you have described in your last comment is essentially what we do now, but I think we are just off on how to implement the guidance. It sounds like we want to use AWS Transit Gateway Attachment capitalization when we are referring to the AWS-specific feature by name, but we actually don't do that anywhere in these docs. In the top-level descriptions, we are referring to our HCP Terraform resource by name (ie. a human-readable version of aws_transit_gateway_attachment).
I'm not familiar with the term "AWS Network Peering resource" though. If it's a feature of AWS's, I say keep it capitalized, but if not, we might want to revise to "AWS network peering resource".
So it sounds like we would want The AWS network peering resource for peering, and The AWS transit gateway attachment resource for TGW. I can just update both resources in this PR.
These changes will probably be easiest to review one commit at a time. The updates largely come from items we ran into while working on the TGW resource, but did not yet backport to the other resources: