RFD 0196 - Add opinionated intro to product #50987

thedevelopnik · 2025-01-13T15:43:39Z

Signed-off-by: Dave Sudia <15764229+thedevelopnik@users.noreply.github.com>

r0mant

High-level premise makes sense but it's a bit hard to provide better feedback about the UX without seeing more specifics like what is it actually that we want to implement and what those flows would look like. I would take 1 or 2 initial flows you think we should prioritize and explore those in detail.

r0mant · 2025-01-13T23:56:42Z

rfd/0196-opinionated-intro.md

+
+This implementation is limited to the persona of a new admin. In the future we should have similar intros for other personas like dev users, SSO users (an access use case similar to our own internal platform.teleport.sh), admins coming into an existing cluster, etc. Product will do future work with design and other teams to formulate these personas. This means we need to define “a new admin.” Since we do not have user types in the app, simply roles, we’ll need to define this via one or a combination of roles, and this should only show up for newly created clusters.
+
+### Out of Bounds


Empty section?

Yeah, I didn't have anything to put there but held in case out-of-bounds things are identified in discussion.

r0mant · 2025-01-14T16:40:30Z

rfd/0196-opinionated-intro.md

+  * Scalability
+
+### Rough outline of the content
+* Quickstart


Are these supposed to be "knowledge-base" type articles/helpers or something actionable a user actually does or a mixture of both? It's not very clear from the descriptions - for example what is "Roles -> Strategy"?

This also lists a lot of things. Less is more - I think we should identify and start with just a handful (maybe 1 or 2) of very specific flows we want to highlight and spec those out in detail so we understand what the scope here is.

I think a mix that leans heavily towards a actionable tutorials. Things like Roles -> Strategy would definitely be more knowledge-base-like, and maybe we taking anything like that and change it to a link to the docs. One reason for doing this is to give people more context and instruction on why they're doing what they're doing, but the outline is definitely still rough.

There's also content that could be cut, but part of the spec here is giving people the option to cut that content on their own. I will argue for basically keeping the list as it is here. But for figuring out the total scope it makes sense to flesh out 1 or 2 of the areas, I will get on that!

Specifically I believe that having more topics does not increase the scope for design or engineering, mostly on me to write the content.

Another way we could slice this is to think of it from 'what I have perspective', for example if I'm on AWS. I would want to learn about connecting EC2 using AWS IAM Join token, AWS console access, JIT access for AWS and Policy for AWS.

+1 or picking 1 or 2 and flushing it out as part of this RFD.

r0mant · 2025-01-14T16:41:29Z

rfd/assets/0196-sketch1.jpeg

Can you use either LucidChart or Excalidraw for wireframes/mockups?

Yeah, I can convert these over to FigJam which is the tool I have an account for, and switch the images to links to there. I normally draw there on my iPad but with the new rules about what we can access on devices couldn't get in, so just wanted to get something up for review. But I'll do a pass now with wireframe vs drawing.

Moved the sketches to FigJam board and will be putting more there as I flesh out the 2 routes. Updated the RFD to point there, removed the images here, and updated and the rendered link.

rfd/0196-opinionated-intro.md

benarent · 2025-01-14T23:37:47Z

rfd/0196-opinionated-intro.md

+Key context to provide in each guide is some pros/cons and the why of each topic, especially for topics like Users/Auth. Why use local users vs SSO? This is a good place to incorporate info from SE like in the SSO one saying “you may not have permission to set up your SSO yet, in that case local users are a great place to get started.”
+
+The following fat marker sketches are meant as a jumping off point for design.
+* [side bar and intro page](./assets/0196-sketch1.jpeg)


We might want to consider how to host / privacy of these videos. YouTube is often banned, but we could self-host or leverage a 3rd party tool such as https://www.mux.com/ to have greater control.

Good call out, and if it adds a lot to scope this is a place I'm fine cutting, just not having the video.

benarent · 2025-01-14T23:39:33Z

rfd/0196-opinionated-intro.md

+
+## Overview
+
+### Problem


For scope of this RFD, are we thinking about it for Teleport Cloud, Teleport Community, and Teleport Enterprise.

I think Cloud and Enterprise since they would have more feature parity, less checks to worry about on what to display. Unless it's just as easy to have it in community as well.

Signed-off-by: Dave Sudia <david.sudia@goteleport.com>

Co-authored-by: Ben Arent <ben@goteleport.com>

webvictim · 2025-01-20T16:58:23Z

rfd/0196-opinionated-intro.md

+
+### Rabbit Holes
+
+This implementation is limited to the persona of a new admin. In the future we should have similar intros for other personas like dev users, SSO users (an access use case similar to our own internal platform.teleport.sh), admins coming into an existing cluster, etc. Product will do future work with design and other teams to formulate these personas. This means we need to define “a new admin.” Since we do not have user types in the app, simply roles, we’ll need to define this via one or a combination of roles, and this should only show up for newly created clusters.


Will we still show the intro to all new SSO users signing into the cluster, or hide it completely?

Often with prospects, one of the things they want to get done first is to set up an SSO connector and have their teammates sign into the cluster so they can test it for themselves. If we were to hide the intro from them by default, we might be missing out on discoverability.

Perhaps we should have a way to enable it for a given user, or define whether users signing in via SSO should see the intro or not? Maybe they see it if they have the editor role or some set of admin permissions we deem sufficient?

webvictim · 2025-01-20T16:58:55Z

rfd/0196-opinionated-intro.md

+
+Above the guide is a progress bar or other indicator that gives the user some sense of how close to “done” they are with learning the product. This is not an indicator of them being done fully implementing the product.
+
+Within the content we want to weave a concepts in:


Suggested change

Within the content we want to weave a concepts in:

Within the content we want to weave in the concepts of:

webvictim · 2025-01-20T17:00:35Z

rfd/0196-opinionated-intro.md

+### Rough outline of the content
+* Quickstart
+  * You are a local user, what does that mean?
+  * You have the “access” role, what does that mean?


We should also explain the concept of built-in/Teleport-managed roles vs custom roles that you build yourself.

+1 if we can find a way to mark built-in roles somehow as being "different" within the product and encouraging their use over custom roles wherever appropriate.

webvictim · 2025-01-20T17:04:12Z

rfd/0196-opinionated-intro.md

+
+Within the content we want to weave a concepts in:
+* Tokens
+* Agents


One thing we should really focus on after a user has been introduced to an agent is the idea of "one Teleport agent/process can run multiple services". This works nicely into tokens and what they're used for, IMO, as it builds up the idea of Teleport as a modular platform.

Essentially the concept of:

the job of an agent is mostly to run "close to" target resources and relay network connectivity to them

if you have multiple resources in one place, you can use the same agent/process to get connectivity to them just by modifying the agent's Teleport config and restarting it.

Our docs are currently not consistent at all in terms of showing how to add a new service to a running agent (three different services will show you three different methods) so this might also need to be tackled as part of the project, if we want a good tie-in between the guides in the UI and the docs they're ultimately backed by.

webvictim · 2025-01-20T17:10:40Z

rfd/0196-opinionated-intro.md

+Above the guide is a progress bar or other indicator that gives the user some sense of how close to “done” they are with learning the product. This is not an indicator of them being done fully implementing the product.
+
+Within the content we want to weave a concepts in:
+* Tokens


One thing that I think would be very valuable is teaching people about the different resource types/protocols that Teleport supports and how they're split up into different services.

There's also esoteric stuff like:

the Teleport ssh_service has a 1:1 relationship between a server and being able to connect to it using SSH, it has no "relay" capability

assuming it's deployed with the teleport-kube-agent Helm chart, the Teleport kubernetes_service generally has a 1:1 mapping between target Kubernetes cluster and Kubernetes service (but this goes out of the window when auto-discovery gets involved, so might be harder to explain)

the other "primary" Teleport services (db_service, app_service and windows_desktop_service) have a 1:many relationship which allows one service to relay connections to many different resources inside your target environment.

I'd really encourage us to use diagrams to show where the services sit inside an environment and how the data flows between the user and the resource.

thedevelopnik added 2 commits January 13, 2025 08:37

add opinionated intro to product RFD

9ecfad1

Signed-off-by: Dave Sudia <15764229+thedevelopnik@users.noreply.github.com>

fix iamge links in rfd 0196

1b4e57a

Signed-off-by: Dave Sudia <15764229+thedevelopnik@users.noreply.github.com>

thedevelopnik added rfd Request for Discussion size/lg no-changelog Indicates that a PR does not require a changelog entry labels Jan 13, 2025

thedevelopnik requested review from klizhentas, r0mant, benarent, webvictim, roraback, xinding33, ptgott and stevenGravy January 13, 2025 15:43

thedevelopnik self-assigned this Jan 13, 2025

thedevelopnik changed the title ~~RFD 1096 - Add opinionated intro to product~~ RFD 0196 - Add opinionated intro to product Jan 13, 2025

github-actions bot requested review from jimbishopp and zmb3 January 13, 2025 15:44

github-actions bot added the size/md label Jan 13, 2025

r0mant reviewed Jan 14, 2025

View reviewed changes

benarent reviewed Jan 14, 2025

View reviewed changes

rfd/0196-opinionated-intro.md Outdated Show resolved Hide resolved

benarent reviewed Jan 14, 2025

View reviewed changes

thedevelopnik and others added 2 commits January 16, 2025 08:59

update link to design assets for rfd 0196

a3443a7

Signed-off-by: Dave Sudia <david.sudia@goteleport.com>

Update title of rfd 0196

5dfb3db

Co-authored-by: Ben Arent <ben@goteleport.com>

webvictim reviewed Jan 20, 2025

View reviewed changes

benarent mentioned this pull request Jan 21, 2025

update license to do logic in teleport configure #51220

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFD 0196 - Add opinionated intro to product #50987

RFD 0196 - Add opinionated intro to product #50987

thedevelopnik commented Jan 13, 2025 •

edited

Loading

r0mant left a comment

r0mant Jan 13, 2025

thedevelopnik Jan 14, 2025

r0mant Jan 14, 2025

thedevelopnik Jan 14, 2025

thedevelopnik Jan 14, 2025

benarent Jan 14, 2025

r0mant Jan 14, 2025

thedevelopnik Jan 14, 2025 •

edited

Loading

thedevelopnik Jan 16, 2025 •

edited

Loading

benarent Jan 14, 2025

thedevelopnik Jan 15, 2025

benarent Jan 14, 2025

thedevelopnik Jan 15, 2025

webvictim Jan 20, 2025 •

edited

Loading

webvictim Jan 20, 2025

webvictim Jan 20, 2025

webvictim Jan 20, 2025

webvictim Jan 20, 2025


		This implementation is limited to the persona of a new admin. In the future we should have similar intros for other personas like dev users, SSO users (an access use case similar to our own internal platform.teleport.sh), admins coming into an existing cluster, etc. Product will do future work with design and other teams to formulate these personas. This means we need to define “a new admin.” Since we do not have user types in the app, simply roles, we’ll need to define this via one or a combination of roles, and this should only show up for newly created clusters.

		### Out of Bounds


		### Rabbit Holes

		This implementation is limited to the persona of a new admin. In the future we should have similar intros for other personas like dev users, SSO users (an access use case similar to our own internal platform.teleport.sh), admins coming into an existing cluster, etc. Product will do future work with design and other teams to formulate these personas. This means we need to define “a new admin.” Since we do not have user types in the app, simply roles, we’ll need to define this via one or a combination of roles, and this should only show up for newly created clusters.


		Above the guide is a progress bar or other indicator that gives the user some sense of how close to “done” they are with learning the product. This is not an indicator of them being done fully implementing the product.

		Within the content we want to weave a concepts in:

	Within the content we want to weave a concepts in:
	Within the content we want to weave in the concepts of:

RFD 0196 - Add opinionated intro to product #50987

Are you sure you want to change the base?

RFD 0196 - Add opinionated intro to product #50987

Conversation

thedevelopnik commented Jan 13, 2025 • edited Loading

r0mant left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thedevelopnik Jan 14, 2025 • edited Loading

Choose a reason for hiding this comment

thedevelopnik Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

webvictim Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

thedevelopnik commented Jan 13, 2025 •

edited

Loading

thedevelopnik Jan 14, 2025 •

edited

Loading

thedevelopnik Jan 16, 2025 •

edited

Loading

webvictim Jan 20, 2025 •

edited

Loading