Skip to content

[v10] Organize docs guide sections chronologically#15735

Merged
ptgott merged 1 commit into
branch/v10from
paul.gottschling/15357-bp-v10
Aug 30, 2022
Merged

[v10] Organize docs guide sections chronologically#15735
ptgott merged 1 commit into
branch/v10from
paul.gottschling/15357-bp-v10

Conversation

@ptgott
Copy link
Copy Markdown
Contributor

@ptgott ptgott commented Aug 22, 2022

Backports #15357

  • Organize docs guide sections chronologically

This change aims to make docs navigation easier by organizing some docs
sections according to the sequence of steps a user would take to set up
Teleport.

The current docs organization uses a variety of categories and schemes
to organize the docs. For example, there is a "Home" section that
includes the Changelog, Installation page, and Getting Started guides; a
"Setup" section that includes references and admin guides; and
edition-specific sections (Enterprise, Cloud). For a user who is setting
up Teleport--or who has already done some setup work and wants more
advanced instructions--it's difficult to know where in the docs to find
the right information.

This change organizes our how-to guides into the following categories
that describe the process of setting up Teleport:

  • Try out Teleport
  • Deploy a Cluster (including choosing an edition)
  • Configure Access (including SSO, RBAC, and Access Requests)
  • Manage your Cluster (admin guides, operations, etc.)
  • Use Teleport (this section already exists)

I moved the Reference section after this chronology, since users can
access the reference guides anywhere in the setup process.

As part of the change, I have also moved the content from the
"Enterprise" and "Cloud" sections into "Deploy a Cluster", since this
content has to do with how to deploy a specific edition of Teleport.

Note that this change does not attempt to reorganize our
protocol-specific sections. While adding resources is part of the
Teleport setup process, we have a lot of content in our
protocol-specific sections, and moving it all into a single section
related to adding resources to a cluster would (a) exceed the maximum
depth for subsections in the nav bar and (b) cause more confusion than
it alleviates.

  • Respond to PR feedback
  • Create a "Compliance Frameworks" section of "Configure Access" with
    the FedRAMP and SOC 2 guides
  • Rename "Use Teleport" to "Connect your Client"
  • Move the database GUI client guide into "Connect your Client"
  • Add redirects

  • Fix linter issues

@ptgott ptgott changed the title Organize docs guide sections chronologically [v10] Organize docs guide sections chronologically Aug 22, 2022
@github-actions github-actions Bot requested review from klizhentas and zmb3 August 22, 2022 20:27
@ptgott
Copy link
Copy Markdown
Contributor Author

ptgott commented Aug 22, 2022

We'll probably need to merge this PR first to avoid broken links in Tiles, which currently aren't linted. Also need to apply the edits in this PR, which fixes some malformed links resulting from PR #15357.

@ptgott ptgott force-pushed the paul.gottschling/15357-bp-v10 branch from 6073b03 to 1ab8d8c Compare August 26, 2022 21:54
@ptgott ptgott force-pushed the paul.gottschling/15357-bp-v10 branch 2 times, most recently from de6949d to a58cf28 Compare August 29, 2022 19:52
Backports #15357

* Organize docs guide sections chronologically

This change aims to make docs navigation easier by organizing some docs
sections according to the sequence of steps a user would take to set up
Teleport.

The current docs organization uses a variety of categories and schemes
to organize the docs. For example, there is a "Home" section that
includes the Changelog, Installation page, and Getting Started guides; a
"Setup" section that includes references and admin guides; and
edition-specific sections (Enterprise, Cloud). For a user who is setting
up Teleport--or who has already done some setup work and wants more
advanced instructions--it's difficult to know where in the docs to find
the right information.

This change organizes our how-to guides into the following categories
that describe the process of setting up Teleport:

- Try out Teleport
- Deploy a Cluster (including choosing an edition)
- Configure Access (including SSO, RBAC, and Access Requests)
- Manage your Cluster (admin guides, operations, etc.)
- Use Teleport (this section already exists)

I moved the Reference section after this chronology, since users can
access the reference guides anywhere in the setup process.

As part of the change, I have also moved the content from the
"Enterprise" and "Cloud" sections into "Deploy a Cluster", since this
content has to do with how to deploy a specific edition of Teleport.

Note that this change does _not_ attempt to reorganize our
protocol-specific sections. While adding resources is part of the
Teleport setup process, we have a lot of content in our
protocol-specific sections, and moving it all into a single section
related to adding resources to a cluster would (a) exceed the maximum
depth for subsections in the nav bar and (b) cause more confusion than
it alleviates.

* Respond to PR feedback

- Create a "Compliance Frameworks" section of "Configure Access" with
  the FedRAMP and SOC 2 guides
- Rename "Use Teleport" to "Connect your Client"
- Move the database GUI client guide into "Connect your Client"

* Add redirects

* Fix linter issues
@ptgott ptgott enabled auto-merge (squash) August 30, 2022 16:34
@ptgott ptgott force-pushed the paul.gottschling/15357-bp-v10 branch from a58cf28 to 2c32fff Compare August 30, 2022 16:34
@ptgott ptgott merged commit 73469f9 into branch/v10 Aug 30, 2022
@zmb3 zmb3 deleted the paul.gottschling/15357-bp-v10 branch September 9, 2022 18:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants