Add "How It Works" sections for all major features/protocols

[philip-teleport]

Applies To

How It Works

Details

Currently, the "How It Works" overview covers Database Access, Kubernetes Access, Edge Access and Audit Logging:

It should be updated to include sections on:

• Device Trust
• Desktop Access
• Application Access
• Machine ID

How will we know this is resolved?

Table Of Contents has been updated.

Related Issues

N/A

[codingllama]

I've got a draft for Device Trust, shared with Phil just now.

[zmb3]

This type of issue is likely to sit open for a long time because it is too broad in scope. Smaller more focused issues are easier to prioritize and will get the team's attention much quicker.

[philip-teleport]

Thanks for the feedback, @zmb3. I've created 4 separate issues for new sections on Device Trust, Desktop Access, Application Access and Machine ID and added them as tasks on this issue.

[zmb3]

Note that this page is technically not part of our docs, but rather part of goteleport.com.

I think we should keep this page as a very high level overview rather than duplicating detailed info that belongs in the docs.

[ptgott]

I think we should also review the role and effectiveness of the "How it works" section per #16676 before adjusting any details in the section. It might make more sense to commit resources to architecture guides in the docs site instead.

[strideynet]

It might make more sense to commit resources to architecture guides in the docs site instead.

I saw the Machine ID ticket and popped onto this one to say much the same thing - it feels like a lot of this content is already covered within the Machine ID architectural guide and I'm wary of maintaining too many variations of the same knowledge.

[zmb3]

Hi @philip-teleport, I talked with the team and the general consensus is that this How it Works page should not replace or duplicate the detailed information on our docs site.

These issues are proposing a solution rather than pointing out a specific problem. If there are specific things that you'd expect to see in our docs that do not exist today, you're welcome to raise a focused issue that describes what you think is missing.

We're going to keep #16676 open to track the work ensure that this how it works page is effective and contains the right level of detail, but we're not likely to expand that page to cover each and every feature and protocol, so I'm going to close the rest of these as not planned.