Terraform-provider-aws: Proposal: Data Source and Resource Documentation Usability Improvements

[bflad]

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 "me too" comments, 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

Proposal

I would like to propose three separate but related usability improvements for the website:

• Splitting the Data Sources section (bundling data source and resources by AWS Service but another option would be doing AWS Service Data Source sections like we do AWS Service Resource sections)
• Prepending data. to data source names in the sidebar
• Ensuring resources include Resource: in the main header title of the opened resource documentation pages (we only do Data Source: for data sources currently)

Each of these can and should be considered individually. 😄

References

• Related sidebar improvements: #8224

[bflad]

I believe we are leaning towards something like:

• Service 1
  
  
  
  • Data Sources
  
  
  • aws_XXX
  
  
  • Resources
  
  
  • aws_YYY
  
  
  • aws_ZZZ
  
  
• Service 2
  ...

In addition to the above hierarchy, we are thinking it may make sense to introduce service overview pages that can highlight the bigger picture of configuring a service (somewhere between the resource documentation examples and a full fledged walkthrough guide). This expanded hierarchy would also offer a great way to link directly to the repository examples directories and the guides like the EKS Getting Started Guide. Much of this work is very early in the design phases and there are no current timelines for these additions.

In our initial discussion of the original proposal, the data. idea did not feel correct so removing. 👍

[bflad]

Here's a quick demonstration with the sub navigations expanded for the top 3 services. The top level Data Sources navigation would be removed. Combined with the upcoming dynamic sidebar searching, which will show the navigation headers up to matching elements, this will look pretty slick.

[bflad]

Here's a better view, with the WIP search bar:

[hashibot[bot]]

I'm going to lock this issue because it has been closed for _30 days_ ⏳. This helps our maintainers find and focus on the active issues.

If you feel this issue should be reopened, we encourage creating a new issue linking back to this one for added context. Thanks!