Skip to content

Simplify the Getting Started experience#25415

Merged
ptgott merged 1 commit intomasterfrom
paul.gottschling/2023-05-01-simplify-getting-started
May 2, 2023
Merged

Simplify the Getting Started experience#25415
ptgott merged 1 commit intomasterfrom
paul.gottschling/2023-05-01-simplify-getting-started

Conversation

@ptgott
Copy link
Copy Markdown
Contributor

@ptgott ptgott commented May 1, 2023

This change makes the experience of getting started with Teleport more opinionated and more precisely molded around our intended audience. The assumption is that people who want to go through our getting started experience are skilled technologists who:

  • Are curious about how Teleport works and want to tinker with a toy cluster
  • Need to set up a production cluster in order to protect their infrastructure, in which case a toy cluster is less important than a way to get started with the real thing

Promote the "Linux Server" guide

Make the "Linux Server" guide the definitive introduction to OSS Teleport by removing other "Try out Teleport" guides and moving this one to the "Home" section. We want to remove the need for users to decide which getting started guide to try, and this guide is the only one that lets users spin up a fully fledged demo cluster besides the Digital Ocean guide.

To let users know about the DigitalOcean 1-Click droplet, this change links to our DigitalOcean 1-Click app from within the Linux Server guide. It also advises users who don't meet the Linux Server guide prerequisites to sign up for a Teleport Enterprise Cloud free trial.

This change also removes the Docker guide and redirects Docker-related traffic to the Installation page, since the Docker guide is more of a Getting Started guide than an integration guide, and our Installation page already includes Docker setup information.

Edit the Linux Server getting started guide

  • Remove Application Service instructions, since it can turn off users who, for example, don't use Python or don't want to run the Application Service (plus we already mention it at the end of the guide for users who do want to run this service).

  • Update installation instructions to use our one-liner.

  • Make this guide more explicitly focused on the Open Source edition, removing Enterprise instructions. Users who want to tinker with Teleport will not be interested in the Enterprise edition.

  • Add session recording instructions. Most of the content of the Linux Server guide has to do with setting up Teleport, rather than seeing Teleport features, so I wanted to adjust this balance a bit.

  • Remove the permission warning. It takes up around 1/4 of the screen height when viewing the page, and we expect our intended audience to know this information already.

Change the Enterprise information architecture

  • Remove the Enterprise "Getting Started" guide: This guide shows you how to deploy a demo Teleport Enterprise cluster, which is sort of a contradiction in terms. Enterprise users expect a production-grade cluster, which is not what you get in this guide.

  • In the Enterprise Introduction page, include instructions to read the Deployment Guides, which show how to set up a mature HA deployment, plus a recommendation to use Teleport Enterprise Cloud unless you need the Enterprise-specific features explained in this guide.

Copy link
Copy Markdown
Collaborator

@zmb3 zmb3 left a comment

Choose a reason for hiding this comment

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

Nice simplification and thanks for the detailed PR description!

This change makes the experience of getting started with Teleport more
opinionated and more precisely molded around our intended audience. The
assumption is that people who want to go through our getting started
experience are skilled technologists who:

- Are curious about how Teleport works and want to tinker with a toy
  cluster
- Need to set up a production cluster in order to protect their
  infrastructure, in which case a toy cluster is less important than a
  way to get started with the real thing

Promote the "Linux Server" guide
--------------------------------

Make the "Linux Server" guide the definitive introduction to OSS
Teleport by removing other "Try out Teleport" guides and moving this one
to the "Home" section. We want to remove the need for users to decide
which getting started guide to try, and this guide is the only one that
lets users spin up a fully fledged demo cluster besides the Digital
Ocean guide.

To let users know about the DigitalOcean 1-Click droplet, this change
links to our DigitalOcean 1-Click app from within the Linux Server
guide. It also advises users who don't meet the Linux Server guide
prerequisites to sign up for a Teleport Enterprise Cloud free trial.

This change also removes the Docker guide and redirects Docker-related
traffic to the Installation page, since the Docker guide is more of a
Getting Started guide than an integration guide, and our Installation
page already includes Docker setup information.

Edit the Linux Server getting started guide
-------------------------------------------

- Remove Application Service instructions, since it can turn off users
  who, for example, don't use Python or don't want to run the
  Application Service (plus we already mention it at the end of the
  guide for users who do want to run this service).

- Update installation instructions to use our one-liner.

- Make this guide more explicitly focused on the Open Source edition,
  removing Enterprise instructions. Users who want to tinker with
  Teleport will not be interested in the Enterprise edition.

- Add session recording instructions. Most of the content of the Linux
  Server guide has to do with setting up Teleport, rather than seeing
  Teleport features, so I wanted to adjust this balance a bit.

- Remove the permission warning. It takes up around 1/4 of the screen
  height when viewing the page, and we expect our intended audience to
  know this information already.

Change the Enterprise information architecture
----------------------------------------------

- Remove the Enterprise "Getting Started" guide: This guide shows you
  how to deploy a demo Teleport Enterprise cluster, which is sort of a
  contradiction in terms. Enterprise users expect a production-grade
  cluster, which is not what you get in this guide.

- In the Enterprise Introduction page, include instructions to read the
  Deployment Guides, which show how to set up a mature HA deployment,
  plus a recommendation to use Teleport Enterprise Cloud unless you need
  the Enterprise-specific features explained in this guide.
@ptgott ptgott force-pushed the paul.gottschling/2023-05-01-simplify-getting-started branch from 92f3a6e to 1932a8d Compare May 2, 2023 15:23
Copy link
Copy Markdown
Contributor

@xinding33 xinding33 left a comment

Choose a reason for hiding this comment

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

These are exactly the changes we discussed. Thanks for putting it together! @ptgott

@ptgott ptgott added this pull request to the merge queue May 2, 2023
Merged via the queue into master with commit 2a7be95 May 2, 2023
@ptgott ptgott deleted the paul.gottschling/2023-05-01-simplify-getting-started branch May 2, 2023 21:39
@public-teleport-github-review-bot
Copy link
Copy Markdown

@ptgott See the table below for backport results.

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

ptgott added a commit that referenced this pull request Jun 1, 2023
Closes #27186

Our attempt to simplify the getting started experience (#25415)
condensed all getting started instructions into the Linux Server guide.
This removed the only example in the docs for running Teleport on
Docker. Our Installation page's Docker instructions contain only a list
of supported images.

This change expands our Installation guide to provide more comprehensive
instructions for running Teleport on Docker, including information on
ports and file mounts as well as an example of running a Teleport
container.

This also breaks up the image tables. This lets us share descriptive
text between Enterprise and OSS tabs, and makes the information easier
to read.
ptgott added a commit that referenced this pull request Jun 28, 2023
Closes #27186

Our attempt to simplify the getting started experience (#25415)
condensed all getting started instructions into the Linux Server guide.
This removed the only example in the docs for running Teleport on
Docker. Our Installation page's Docker instructions contain only a list
of supported images.

This change expands our Installation guide to provide more comprehensive
instructions for running Teleport on Docker, including information on
ports and file mounts as well as an example of running a Teleport
container.

This also breaks up the image tables. This lets us share descriptive
text between Enterprise and OSS tabs, and makes the information easier
to read.
github-merge-queue Bot pushed a commit that referenced this pull request Jun 28, 2023
* Expand Docker installation instructions

Closes #27186

Our attempt to simplify the getting started experience (#25415)
condensed all getting started instructions into the Linux Server guide.
This removed the only example in the docs for running Teleport on
Docker. Our Installation page's Docker instructions contain only a list
of supported images.

This change expands our Installation guide to provide more comprehensive
instructions for running Teleport on Docker, including information on
ports and file mounts as well as an example of running a Teleport
container.

This also breaks up the image tables. This lets us share descriptive
text between Enterprise and OSS tabs, and makes the information easier
to read.

* Respond to zmb3 feedback

* Respond to stevenGravy feedback

Add more context on the intended scope of the example.

* Respond to alexfornuto feedback

* Respond to alexfornuto feedback
github-actions Bot pushed a commit that referenced this pull request Jun 28, 2023
Closes #27186

Our attempt to simplify the getting started experience (#25415)
condensed all getting started instructions into the Linux Server guide.
This removed the only example in the docs for running Teleport on
Docker. Our Installation page's Docker instructions contain only a list
of supported images.

This change expands our Installation guide to provide more comprehensive
instructions for running Teleport on Docker, including information on
ports and file mounts as well as an example of running a Teleport
container.

This also breaks up the image tables. This lets us share descriptive
text between Enterprise and OSS tabs, and makes the information easier
to read.
github-actions Bot pushed a commit that referenced this pull request Jun 28, 2023
Closes #27186

Our attempt to simplify the getting started experience (#25415)
condensed all getting started instructions into the Linux Server guide.
This removed the only example in the docs for running Teleport on
Docker. Our Installation page's Docker instructions contain only a list
of supported images.

This change expands our Installation guide to provide more comprehensive
instructions for running Teleport on Docker, including information on
ports and file mounts as well as an example of running a Teleport
container.

This also breaks up the image tables. This lets us share descriptive
text between Enterprise and OSS tabs, and makes the information easier
to read.
github-merge-queue Bot pushed a commit that referenced this pull request Jun 29, 2023
* Expand Docker installation instructions

Closes #27186

Our attempt to simplify the getting started experience (#25415)
condensed all getting started instructions into the Linux Server guide.
This removed the only example in the docs for running Teleport on
Docker. Our Installation page's Docker instructions contain only a list
of supported images.

This change expands our Installation guide to provide more comprehensive
instructions for running Teleport on Docker, including information on
ports and file mounts as well as an example of running a Teleport
container.

This also breaks up the image tables. This lets us share descriptive
text between Enterprise and OSS tabs, and makes the information easier
to read.

* Respond to zmb3 feedback

* Respond to stevenGravy feedback

Add more context on the intended scope of the example.

* Respond to alexfornuto feedback

* Respond to alexfornuto feedback
github-merge-queue Bot pushed a commit that referenced this pull request Jun 29, 2023
* Expand Docker installation instructions

Closes #27186

Our attempt to simplify the getting started experience (#25415)
condensed all getting started instructions into the Linux Server guide.
This removed the only example in the docs for running Teleport on
Docker. Our Installation page's Docker instructions contain only a list
of supported images.

This change expands our Installation guide to provide more comprehensive
instructions for running Teleport on Docker, including information on
ports and file mounts as well as an example of running a Teleport
container.

This also breaks up the image tables. This lets us share descriptive
text between Enterprise and OSS tabs, and makes the information easier
to read.

* Respond to zmb3 feedback

* Respond to stevenGravy feedback

Add more context on the intended scope of the example.

* Respond to alexfornuto feedback

* Respond to alexfornuto feedback
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.

3 participants