Cloud Documenation - Getting Started & other cloud docs needs improvement

[Valien]

Details

With 6.0 on the cusp of release the Getting Started documentation needs some improvements.

We were chatting in the SE team and here are a few document suggestions from @stevenGravy & the others:

• Provide a very brief definition of what is the cloud offering
• Needs to show the cloud pages
• Show adding other users and roles
• Show adding multiple resources (ssh, k8s, db, web app)
• Add OSX and Windows client library instructions (similar to other getting started pages that show this info).
• Maybe add a link to the Cloud Roadmap - showcasing upcoming improvements/upgrades. This builds excitement on the growth of Cloud and what is yet to come.

Basically, it is very sparse right now and undersells Teleport Cloud.

Also if someone is looking to adopt cloud I also think the Cloud button on the menu on the left should be top of the list and made so that it is up-front and easily accessible (make it stand out).

And the "improve the docs" button goes to a 404 currently.

Category

• Improve Existing

[ptgott]

Hi @Valien, I had a few questions about this issue:

Provide a very brief definition of what is the cloud offering

We now have this here. Do any improvements need to be made?

Needs to show the cloud pages

Does "the cloud pages" refer to the Cloud web UI?

Maybe add a link to the Cloud Roadmap - showcasing upcoming improvements/upgrades. This builds excitement on the growth of Cloud and what is yet to come.

Where is the Cloud Roadmap available now?

Also if someone is looking to adopt cloud I also think the Cloud button on the menu on the left should be top of the list and made so that it is up-front and easily accessible (make it stand out).

Let's spin this one off into an issue for gravitational/next. Would the intention be for this to update automatically based on the referrer (so we'd need some mapping between the Referer header and some kind of menu emphasis setting), or would it be okay to, say, rearrange the menu based on a query string (e.g., goteleport.com/docs/?menu-emphasis=cloud), so you would share the URL with prospects/customers manually?

[Valien]

Hi @ptgott - thanks for the updates on this. The cloud doc improvements are good so far! Not sure when some of those were added but probably since I opened this issue. :)

I think my "cloud pages" was in reference to the Teleport UI. That can be ignored as our general information across our docs illustrates the features and is on par with both installs (self and SaaS).

One thing that might be helpful is a combing through our docs as some guides do not mention our SaaS offering in the pre-requisites and I have had some questions from customers asking if they are the same steps.

I know the Cloud team does post some internal roadmaps but when I originally opened this issue the cloud was so new that there wasn't much on features and what was coming.

I think your suggestions on the link is fine.

[ptgott]

I've made a list of docs pages with "Prerequisites" sections that do not mention Teleport Cloud. I'll make time to go through these and see what edits we need to make.

I used this script:

results=$(find docs/pages -name "*.mdx" -exec awk '
# p: whether we are in a prerequisite section
# t: whether a prerequisite section exists in the doc
# cloud: number of Teleport Cloud mentions in the Prerequisites section
BEGIN{p=0; t=0; cloud=0} 

# We are in the Prerequisites section
/# Prerequisite/{p=1; t=1; next;}

# We have left the Prerequisites section
p==1 && /^#{1,} [A-Za-z0-9]+/{p=0;}

# There is a mention of Teleport Cloud in the Prerequisites section
p==1 && /Teleport [cC]loud/{cloud++}

# Print the filename only if there is a Prerequisites section
END{if (t==1){ printf "%s:%s\n", FILENAME, cloud;}}' {} \;)

total_count=$(echo "$results" | wc -l | tr -d "[[:space:]]");
zero_count=$(echo "$results" | grep "0$" | wc -l | tr -d "[[:space:]]");
echo -e "Summary: No cloud references in ${zero_count}/${total_count} files with Prerequisites sections\n";
echo "$results";

Here are the results:

Summary: No cloud references in 35/50 files with Prerequsites sections

docs/pages/database-access/guides/mongodb-atlas.mdx:0
docs/pages/database-access/guides/cockroachdb-self-hosted.mdx:0
docs/pages/database-access/guides/postgres-redshift.mdx:0
docs/pages/database-access/guides/mongodb-self-hosted.mdx:0
docs/pages/database-access/guides/rds.mdx:0
docs/pages/access-controls/getting-started.mdx:1
docs/pages/access-controls/guides/per-session-mfa.mdx:1
docs/pages/access-controls/guides/impersonation.mdx:1
docs/pages/access-controls/guides/webauthn.mdx:1
docs/pages/access-controls/guides/locking.mdx:1
docs/pages/access-controls/guides/role-templates.mdx:1
docs/pages/access-controls/guides/dual-authz.mdx:1
docs/pages/access-controls/guides/u2f.mdx:1
docs/pages/enterprise/sso/google-workspace.mdx:0
docs/pages/enterprise/sso/azuread.mdx:0
docs/pages/enterprise/getting-started.mdx:0
docs/pages/enterprise/workflow/ssh-approval-mattermost.mdx:0
docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx:0
docs/pages/enterprise/workflow/ssh-approval-jira-server.mdx:0
docs/pages/enterprise/workflow/ssh-approval-slack.mdx:2
docs/pages/enterprise/hsm.mdx:0
docs/pages/desktop-access/getting-started.mdx:0
docs/pages/kubernetes-access/getting-started/agent.mdx:0
docs/pages/kubernetes-access/getting-started/cluster.mdx:0
docs/pages/kubernetes-access/guides/multiple-clusters.mdx:0
docs/pages/kubernetes-access/helm/includes/helm-install.mdx:0
docs/pages/setup/admin/adding-nodes.mdx:1
docs/pages/setup/admin/labels.mdx:1
docs/pages/setup/admin/github-sso.mdx:1
docs/pages/setup/admin/users.mdx:1
docs/pages/setup/operations/ca-rotation.mdx:1
docs/pages/setup/operations/scaling.mdx:0
docs/pages/setup/guides/ec2-tags.mdx:0
docs/pages/setup/guides/docker.mdx:0
docs/pages/setup/guides/fluentd.mdx:0
docs/pages/setup/guides/terraform-provider.mdx:0
docs/pages/setup/guides/joining-nodes-aws.mdx:0
docs/pages/setup/deployments/aws-terraform.mdx:0
docs/pages/server-access/getting-started.mdx:0
docs/pages/server-access/guides/vscode.mdx:0
docs/pages/server-access/guides/bpf-session-recording.mdx:0
docs/pages/server-access/guides/restricted-session.mdx:0
docs/pages/server-access/guides/ansible.mdx:1
docs/pages/getting-started/linux-server.mdx:0
docs/pages/getting-started/docker-compose.mdx:0
docs/pages/api/getting-started.mdx:0
docs/pages/production.mdx:0
docs/pages/application-access/getting-started.mdx:0
docs/pages/application-access/guides/api-access.mdx:0
docs/pages/application-access/guides/aws-console.mdx:0

[ptgott]

Editing these pages may require several PRs to avoid a massive review burden (unless it turns out that few changes need to be made), so I have created a table of all the pages that don't mention our cloud offering in the Prerequisites section to track progress.

Page	PR link	Merged?
docs/pages/database-access/guides/mongodb-atlas.mdx	#9681
docs/pages/database-access/guides/cockroachdb-self-hosted.mdx	#9681
docs/pages/database-access/guides/postgres-redshift.mdx	#9681
docs/pages/database-access/guides/mongodb-self-hosted.mdx	#9681
docs/pages/database-access/guides/rds.mdx	#9681
docs/pages/enterprise/sso/google-workspace.mdx	#9962
docs/pages/enterprise/sso/azuread.mdx	#9962
docs/pages/enterprise/getting-started.mdx (not relevant to Cloud users)	N/A	N/A
docs/pages/enterprise/workflow/ssh-approval-mattermost.mdx	https://github.com/gravitational/teleport/pull/9470
docs/pages/enterprise/workflow/ssh-approval-pagerduty.mdx	https://github.com/gravitational/teleport/pull/9470
docs/pages/enterprise/workflow/ssh-approval-jira-server.mdx	https://github.com/gravitational/teleport/pull/9470
docs/pages/enterprise/hsm.mdx	#9962
docs/pages/desktop-access/getting-started.mdx	#9989
docs/pages/kubernetes-access/getting-started/agent.mdx	#9989
docs/pages/kubernetes-access/getting-started/cluster.mdx	#9989
docs/pages/kubernetes-access/guides/multiple-clusters.mdx	#9989
docs/pages/kubernetes-access/helm/includes/helm-install.mdx	#10023
docs/pages/setup/operations/scaling.mdx	#9962
docs/pages/setup/guides/ec2-tags.mdx	#9989
docs/pages/setup/guides/docker.mdx	#9962
docs/pages/setup/guides/fluentd.mdx (actually mentions Teleport Cloud)	N/A	N/A
docs/pages/setup/guides/terraform-provider.mdx (actually mentions Teleport Cloud)	N/A	N/A
docs/pages/setup/guides/joining-nodes-aws.mdx	#10021
docs/pages/setup/deployments/aws-terraform.mdx	#9962
docs/pages/server-access/getting-started.mdx	#10021
docs/pages/server-access/guides/vscode.mdx	#10061
docs/pages/server-access/guides/bpf-session-recording.mdx	#9962
docs/pages/server-access/guides/restricted-session.mdx	#9962
docs/pages/getting-started/linux-server.mdx	#9969
docs/pages/getting-started/docker-compose.mdx	#9969
docs/pages/api/getting-started.mdx	#9969
docs/pages/production.mdx (Page inaccessible due to redirect, so ignoring)	N/A	N/A
docs/pages/application-access/getting-started.mdx	#10021
docs/pages/application-access/guides/api-access.mdx	#9969
docs/pages/application-access/guides/aws-console.mdx	#9969

[ptgott]

Closing this since I used it as a tracking issue for docs guides that did not mention Teleport Cloud in their Prerequisites sections. All of these guides now have PRs associated with them. I am going to start a new tracking issue for preparing our docs pages in high-priority sections for Cloud users.