bflad
Add attribute section alternates
Hey @YakDriver 👋 Thank you for submitting this. Is there some context to why we should enable the variation? This tooling is designed to ensure header consistency.
Hi! 👋
Consistency is the key behind this. The tool has "Argument Reference" (non-plural) but "Attribute_s_ Reference" (plural) instead of "Attribute Reference" (non-plural). Non-plural is correct but it's self inconsistent currently.
Also, we're making a push to use active voice instead of passive. The bylines are currently passive but we're switching to active.
@YakDriver that all sounds great. My point is that we should be striving to have "one implementation to rule them all" rather than introduce variants, such as multiple acceptable headers.
The historical context here is that these content checks were written by using the overwhelming majority of documentation content implementations when everything was still living in the terraform-providers GitHub organization. It was easier to try to get things using that standard than boil the ocean by inventing a new standard then. Times have certainly changed since then.
I'm all for updating this tooling (which is likely to get baked directly into hashicorp/terraform-plugin-docs soon) to follow our current preferred practices. It would be helpful to see all the proposed changes more globally as an issue and introduce them iteratively here before we migrate the check logic.