search

gravitational / teleport

The easiest, and most secure way to access and protect all of your infrastructure.
https://goteleport.com
GNU Affero General Public License v3.0
17.33k stars 1.74k forks source link

Audit some beginner/early-stage Teleport guides #11841

Closed ptgott closed 2 years ago

ptgott commented 2 years ago

Details

Ensure that guides for users in the early stages of setting up Teleport are accurate and straightforward to follow.

While we want all of our guides to have these qualities, this issue focuses on some guides that users first getting acquainted with Teleport are expected to read.

Since these guides provide the basis for following other guides, frustration while working through them can hamper a new user's overall adoption of Teleport.

I will set up a demo environment for the Cloud, Open Source, and Enterprise editions of Teleport, and verify each page separately for each.

Guide PR (Cloud) PR (self-hosted)
/docs/getting-started/linux-server N/A #12236
/docs/installation #12282 #12282
/setup/admin/github-sso/ #11913 #11913
/setup/admin/adding-nodes/ #11913 #12504
/setup/admin/trustedclusters/ #10708 #10708
/setup/admin/labels/ #12034 #12034
/setup/admin/users/ #12001 #12001
/setup/admin/troubleshooting/ #12074 #12074
/setup/admin/graceful-restarts/ N/A #12119
/setup/admin/daemon/ #12038 #12038
/setup/admin/ (add intro paragraph) #11913 #11913
/docs/server-access/guides/openssh/ #12183 #12183

Category

stevenGravy commented 2 years ago

would include:

docs/setup/admin/ - no opening info on what these guides are for. The setup section lacks a intro which nearly all others have /docs/server-access/guides/openssh/ - frequent usage

ptgott commented 2 years ago

The Trusted Clusters guide is one of the longest guides we have by number of lines. Only the aws-terraform guide is longer (the other longer guides are references).

$ find docs/pages -name "*.mdx" -not -wholename "*includes*" -exec bash -c "echo -n \"{}:\"; cat {} | wc -l" \; | sort -k 2 -nr | head -n 10
docs/pages/kubernetes-access/helm/reference/teleport-cluster.mdx:    1537
docs/pages/setup/reference/cli.mdx:    1486
docs/pages/kubernetes-access/helm/reference/teleport-kube-agent.mdx:    1357
docs/pages/setup/deployments/aws-terraform.mdx:     843
docs/pages/setup/reference/config.mdx:     767
docs/pages/setup/admin/trustedclusters.mdx:     729
docs/pages/server-access/guides/tsh.mdx:     721
docs/pages/setup/reference/backends.mdx:     686
docs/pages/kubernetes-access/helm/guides/aws.mdx:     534
docs/pages/desktop-access/getting-started.mdx:     489

We could consider splitting this guide, though we would need to move it out of the /setup/admin section since this can't accommodate another directory level.

ptgott commented 2 years ago

This is done