Enable community contributed documentation to coexist with generated

[breathingdust]

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave "+1" or other comments that do not add relevant new information or questions, they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment
• The resources and data sources in this provider are generated from the CloudFormation schema, so they can only support the actions that the underlying schema supports. For this reason submitted bugs should be limited to defects in the generation and runtime code of the provider. Customizing behavior of the resource, or noting a gap in behavior are not valid bugs and should be submitted as enhancements to AWS via the CloudFormation Open Coverage Roadmap.

Description

Currently the provider documentation that lives on the registry is wholly generated from the CloudFormation schema. This means that we are limited to attribute level and resource level descriptions that are generally fairly terse in nature. The "classic" AWS Provider has hand written documentation which includes much richer examples, notes and guides sourced from the community that make for a much more useful experience.

While resource behavior should remain wholly generated, we should enable the community to append information to the generated documentation to make for a better experience more inline with what Terraform practitioners are used to.

References

• Example Schema Resource Description
• Example Schema Attribute Description
• AWS Provider S3 Bucket Documentation
• AWS Cloud Control Provider S3 Bucket Documentation
• hashicorp/terraform-plugin-docs