Develop a more opinionated information architecture

[ptgott]

Details

Based on conversation with @xinding33, we want to plan a new information architecture for the documentation site that makes it easier for users to find the most helpful content for their needs. The current docs site addresses users with a mix of job titles/roles, levels of familiarity with Teleport, and Teleport editions (i.e., Cloud, Open Source, or Enterprise). We can plan new menu pages and navigation sidebar links to limit the exposure of users to irrelevant content.

Specific steps:

• Determine how to segment documentation readers (see below for possible categories)
• Propose a new organization (i.e., new links) for navigation sidebars and menu pages. At this stage, individual guides will not be altered.
• Determine if any work needs to be done on the gravitational/docs side to improve navigation

Possible categories to use for segmentation

• Level of familiarity with Teleport

  • beginner: Has not yet run or interacted with Teleport, and may be visiting the docs for the first time
  • intermediate: Is currently trying Teleport, e.g., as part of a Proof of Value assessment
  • advanced: Understands the routine tasks associated with running a Teleport cluster but may need help with specific configuration options, best practices, and new features

• Role within an organization

  • Admins who are managing a Teleport deployment
  • Developers who are adding resources to a Teleport cluster but not necessarily managing the full deployment
  • End-users who only want to access cluster resources (e.g., with `tsh)

• Users of specific Teleport editions

  • Open Source
  • Cloud
  • Enterprise

Category

• Improve Existing

[ptgott]

This may be related to some draft work I've done on hiding navigation menu entries based on scope:

• Hide navigation menu entries based on scope #11383
• Add a ScopeLink component docs#35
• Add ScopeSwitchTile docs#33

[ptgott]

Another related issue: #10199

[ptgott]

Status update: I have a draft plan that I have shared with @xinding33. We will discuss next steps.

[ptgott]

Going to close this to avoid scope creep. We have already added a "Connect your Client" section for end users and reorganized the docs according to a timeline for setting up Teleport by addressing #12787, so for any more work, we should create a separate issue.