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

Reorganize the config reference #21594

Merged
merged 4 commits into from
Feb 24, 2023
Merged

Conversation

ptgott
Copy link
Contributor

@ptgott ptgott commented Feb 9, 2023

Closes #11253

This change breaks up the config reference by moving each Teleport service's configuration settings into a separate YAML snippet, and organizing each YAML snippet into a TabItem within a Tabs with dropdownView enabled. When Teleport Enterprise Cloud doesn't support a service, this change adds a Notice with a message about Teleport Enterprise Cloud in the relevant TabItem.

I thought this approach would be cleaner than alternatives:

  • Including an H2 for each service: With this approach, the configuration reference would be even longer than it is now. With the approach I'm proposing, readers would navigate to "Reference configurations", then choose a service from a dropdown menu: much less scrolling for slightly more clicking.

  • Including another set of TabItems for Teleport editions: I thought about adding a Tabs with a dropdown option for each Teleport edition and a horizontal TabItem for each service, but this would require horizontal scrolling and doesn't scale very well.

  • Including horizontal tabs for each Teleport edition, with an inner dropdown menu for each Teleport service: There is currently no way to do this without multiple Tabs components, which gets messy quickly.

Note that this change does not attempt to copy-edit comments/example values within the configuration snippets. The scope of this change is limited only to reorganization.

Copy link
Contributor

@alexfornuto alexfornuto left a comment

Choose a reason for hiding this comment

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

This could go out as is, but I left some comments for possible improvements.
Additionally, I noticed that the indenting is not consistent between these example files, some use 2 spaces and others use 4.

ptgott and others added 3 commits February 15, 2023 15:08
Closes #11253

This change breaks up the config reference by moving each Teleport
service's configuration settings into a separate YAML snippet, and
organizing each YAML snippet into a `TabItem` within a `Tabs` with
`dropdownView` enabled. When Teleport Enterprise Cloud doesn't support a
service, this change adds a `Notice` with a message about Teleport
Enterprise Cloud in the relevant `TabItem`.

I thought this approach would be cleaner than alternatives:

- **Including an H2 for each service:** With this approach, the
  configuration reference would be even longer than it is now. With the
  approach I'm proposing, readers would navigate to "Reference
  configurations", then choose a service from a dropdown menu: much less
  scrolling for slightly more clicking.

- **Including another set of `TabItem`s for Teleport editions:** I
  thought about adding a `Tabs` with a dropdown option for each Teleport
  edition and a horizontal `TabItem` for each service, but this would
  require horizontal scrolling and doesn't scale very well.

- **Including horizontal tabs for each Teleport edition**, with an inner
  dropdown menu for each Teleport service: There is currently no way to
  do this without multiple `Tabs` components, which gets messy quickly.

**Note** that this change does not attempt to copy-edit comments/example
values within the configuration snippets. The scope of this change is
limited only to reorganization.
Co-authored-by: Alex Fornuto <alex.fornuto@goteleport.com>
@ptgott ptgott force-pushed the paul.gottschling/11253-split-config branch from 812cb6e to ff7b9d8 Compare February 15, 2023 20:08
@zmb3
Copy link
Collaborator

zmb3 commented Feb 21, 2023

I'm not sure this is in line with the goals set out in #15061 and gravitational/docs#93

I'd much prefer all the text be on one page where I can quickly cmd+f and search for it, rather than having to click through tabs.

Thoughts?

@alexfornuto
Copy link
Contributor

alexfornuto commented Feb 21, 2023

searching through one long page works when you know what you're looking for. For those looking to learn about configs, separating them makes it easier to parse.

Additionally this page, as it is, is too big for our crawler:

Record extracted is too big (108KB), the maximum is 97.65625KB

And it's only gonna get bigger as we add product features.

So: What about having instance-wide settings on this page, and sub-pages for each service type? That way each page could still be easily searchable when you know what service type it belongs to, and also easier for someone to learn from going top-to-bottom?

Use headings instead of `TabItem`s to split up sections of the config
reference.
@ptgott
Copy link
Contributor Author

ptgott commented Feb 24, 2023

@alexfornuto I pushed a change to split up the config reference using headings per Zac's feedback. I didn't want to split this into sub-pages, since the docs already has pages devoted to the configuration sections for specific Teleport services, and it would be pretty confusing to have, say, the Application Service config reference in the "Application Access" section (https://goteleport.com/docs/application-access/reference/) as well as in the Reference section.

@ptgott ptgott added this pull request to the merge queue Feb 24, 2023
Merged via the queue into master with commit da0e53e Feb 24, 2023
@public-teleport-github-review-bot

@ptgott See the table below for backport results.

Branch Result
branch/v10 Failed
branch/v11 Failed
branch/v12 Create PR

@ptgott ptgott deleted the paul.gottschling/11253-split-config branch March 22, 2023 21:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Split out Teleport config yaml reference
3 participants