-
Notifications
You must be signed in to change notification settings - Fork 1.8k
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
Conversation
There was a problem hiding this 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.
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>
812cb6e
to
ff7b9d8
Compare
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? |
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:
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.
@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. |
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 aTabs
withdropdownView
enabled. When Teleport Enterprise Cloud doesn't support a service, this change adds aNotice
with a message about Teleport Enterprise Cloud in the relevantTabItem
.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 aTabs
with a dropdown option for each Teleport edition and a horizontalTabItem
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.