Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

website: Update nav sidebar to take advantage of new terraform.io features #8224

Merged
merged 1 commit into from
Apr 8, 2019

Conversation

nfagerlund
Copy link
Member

Reasoning for docs update:

The nav sidebar for the AWS provider docs is very large and hard to get a handle on. It's much nicer if we default the data source/resource sections to collapsed and expand them dynamically... which is now possible, as of this afternoon. (hashicorp/terraform-website#741, hashicorp/terraform-website#744)

(Without this PR, people can still choose to collapse the sections themselves. This PR is just about defaulting the sections to closed.)

Here's a gif:

aws

  • Remove all the calls to sidebar_current() — no longer need it for activating
    the current sections. It's inert now, so it doesn't make any functional difference, but reducing noise can make the sidebar easier to maintain.
  • Default all data source and resource sub-sections to collapsed, since they can
    be opened dynamically now. (The guides section is small and important, so it
    can stay open if you'd like.)
  • Add the optional "Expand/collapse all" control, which is useful if you need to
    cmd-F the entire list of resources.

Relevant Terraform version: n/a.

Community Note

  • Please vote on this pull request by adding a 👍 reaction to the original pull request comment to help the community and maintainers prioritize this request
  • Please do not leave "+1" comments, they generate extra noise for pull request followers and do not help prioritize the request

…tures

- Remove all the calls to `sidebar_current()` — no longer need it for activating
  the current sections.
- Default all data source and resource sub-sections to collapsed, since they can
  be opened dynamically now. (The guides section is small and important, so it
  can stay open if you'd like.)
- Add the optional "Expand/collapse all" control, which is useful if you need to
  cmd-F the entire list of resources.

Combined, these should make it a little easier to get around the AWS provider
pages.
@ghost ghost added size/XXL Managed by automation to categorize the size of a PR. documentation Introduces or discusses updates to documentation. labels Apr 6, 2019
@nfagerlund nfagerlund requested a review from bflad April 6, 2019 00:40
@bflad bflad added the provider Pertains to the provider itself, rather than any interaction with AWS. label Apr 6, 2019
Copy link
Contributor

@bflad bflad left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am ecstatic for this! Huge usability improvements here. While I'm approving this now and would typically merge immediately, its late on a Friday evening and a "big" change so I would like to leave this open to solicit feedback, especially from the other maintainers, which will likely be early next week.

The first potential gotcha that popped into my head was "what about my habit of using cmd-f to find my resource?" but you already solved that by adding the top expand-all button. 🌮 🎉

There have been countless times where data source and resource documentation has been mixed up and defaulting to closing the Data Sources section would likely alleviate those issues at least somewhat. Also mobile browsing was sometimes awful before if the sidebar and all its expanded elements were put at the top before the content. At least it'll be less scrolling now!

I have a few other usability improvements I would like to propose at some point:

  • Splitting the Data Sources section (I think it makes more sense to bundle data source and resources by AWS Service, but another option would be doing AWS Service Data Sources sections like we do AWS Service Resource sections)
  • Prepending data. to data sources in the sidebar
  • Ensuring resources include Resource: in their resource documentation pages

Why don't I just go ahead and make that proposal issue right now. 😅

EDIT: Followup proposal issue can be found here: #8225

@bflad bflad added this to the v2.6.0 milestone Apr 8, 2019
@bflad bflad merged commit 01c9921 into hashicorp:master Apr 8, 2019
@nfagerlund nfagerlund deleted the apr19_sidebar_fixes branch April 8, 2019 21:42
@ghost
Copy link

ghost commented Mar 30, 2020

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!

@ghost ghost locked and limited conversation to collaborators Mar 30, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
documentation Introduces or discusses updates to documentation. provider Pertains to the provider itself, rather than any interaction with AWS. size/XXL Managed by automation to categorize the size of a PR.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants