-
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
Remove Auth/Proxy instructions from DB guides #20308
Conversation
@ptgott what do you think about making these partials part of the bulleted prerequisites list? For example, in - (!docs/pages/includes/edition-prereqs-tabs.mdx!)
- An AWS account with a PostgreSQL AWS Aurora database and permissions to create
and attach IAM policies.
- A host, e.g., an EC2 instance, where you will run the Teleport Database
Service.
- (!docs/pages/includes/tctl.mdx!) |
@alexfornuto For some reason, having the bullets next to these boxes looks a bit strange to me. I think it's the fact that, in the way we often list the prerequisites in docs guides, each list item is a noun phrase ("An AWS account...", "A host...", etc.), so adding the boxes to the list turns the list into a mix of noun phrases and other components. Also, the boxes are pretty bulky, so for me, it looks less like each box belongs to a bullet point and more that there's a stray bullet accidentally appended to the box. What do you think? Is there a clearer way to lay out the prerequisites? |
@ptgott those are good points and well made. Regarding the bulky boxes, I think we can safely remove the details box around the content in the tctl partial. We have it opened by default anyway, and we could review where it's being used and wrap a details box around the call to the partial where we want to preserve it. It doesn't do anything for the Tabs though... Regarding:
The Regarding the look, IMO having each item be in a bullet helps the reader make a mental checklist of things they need to make sure they do / are present before they begin. With the exception of the tctl partial (and only as the final item in a prereqs section), I think we should try to use the bullets for each item, or consider not using them. In this way, the section maintains a consistent formatting. P.S. In any case, don't consider this discussion a blocker for this PR. I'll do a proper review shortly. |
ad89d78
to
8551c8f
Compare
@alexfornuto I've responded to your feedback. I definitely think we should revisit the standard way we write our Prerequisites sections (e.g., |
Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide.
Change H3s to H2s
8551c8f
to
4f9e420
Compare
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
Closes #11538
A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have not set up these services, Teleport has existing instructions that users can follow instead.
This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs.
Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to more places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide.