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

Remove Auth/Proxy instructions from DB guides #20308

Merged
merged 3 commits into from
Feb 3, 2023

Conversation

ptgott
Copy link
Contributor

@ptgott ptgott commented Jan 17, 2023

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.

@alexfornuto
Copy link
Contributor

@ptgott what do you think about making these partials part of the bulleted prerequisites list? For example, in docs/pages/database-access/getting-started.mdx if it was formatted as:

- (!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!)

It would render like this:
image

@ptgott
Copy link
Contributor Author

ptgott commented Jan 18, 2023

@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?

@alexfornuto
Copy link
Contributor

alexfornuto commented Jan 18, 2023

@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:

each list item is a noun phrase ("An AWS account...", "A host...",...

The edition-prereqs-tabs.mdx tab starts with the same phrasing. With the tctl partial being at the end, I'd be OK with it not being bulleted.

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.

@ptgott
Copy link
Contributor Author

ptgott commented Jan 27, 2023

@alexfornuto I've responded to your feedback. I definitely think we should revisit the standard way we write our Prerequisites sections (e.g., edition-prereqs-tabs.mdx and tctl.mdx), though I think we should leave this for a separate issue/PR since it touches on all "*-service" sections in the docs. What would you think of creating a separate issue for this?

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
@ptgott ptgott force-pushed the paul.gottschling/11538-auth-proxy branch from 8551c8f to 4f9e420 Compare February 3, 2023 20:16
@ptgott ptgott added this pull request to the merge queue Feb 3, 2023
Merged via the queue into master with commit 06bf633 Feb 3, 2023
@public-teleport-github-review-bot

@ptgott See the table below for backport results.

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

@alexfornuto alexfornuto deleted the paul.gottschling/11538-auth-proxy branch February 6, 2023 19:10
ptgott added a commit that referenced this pull request Feb 10, 2023
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]>
ptgott added a commit that referenced this pull request Feb 10, 2023
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]>
ptgott added a commit that referenced this pull request Feb 13, 2023
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]>
ptgott added a commit that referenced this pull request Feb 13, 2023
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]>
ptgott added a commit that referenced this pull request Feb 13, 2023
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]>
alexfornuto pushed a commit that referenced this pull request Feb 13, 2023
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]>
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.

Use the start-auth-proxy.mdx partial outside Database Access guides
3 participants