search

gravitational / teleport

The easiest, and most secure way to access and protect all of your infrastructure.
https://goteleport.com
GNU Affero General Public License v3.0
17.53k stars 1.75k forks source link

Reorganize our docs to make Teleport adoption easier #12787

Closed ptgott closed 2 years ago

ptgott commented 2 years ago

Currently, the docs navigation sidebar represents sections from a number of categories:

Initial setup information is somewhat buried. For example, the Getting Started guides are under "Home." The initial setup guide "Adding Nodes" is under /setup/admin/adding-nodes.

With the current setup, users need to identity the topic they want to learn about before they visit the docs site (i.e., via organic search) or after visiting the home page, in order to click on the sidebar link for a specific service.

To help with adoption, it would be great to provide readers with a more choreographed experience that makes it easier to determine which docs to read first and which docs to read next.

Let's consider this issue resolved when we have a definite plan to reorganize the docs as well as a plan to implement it.

ptgott commented 2 years ago

Note that this is a partial solution to https://github.com/gravitational/teleport/issues/12187. We will probably also be making changes to gravitational/docs.

ptgott commented 2 years ago

One solution

Added May 20, 2022. Moved to a comment from the issue description so we can consider other solutions.

In general, the solution would be to organize the documentation sidebar and menu pages chronologically: users would choose an edition, deploy Teleport, configure RBAC, add resources, and manage the cluster. We would think of the navigation sidebar as a timeline, where the highest link is the earliest phase of a user's experience with Teleport.

I've organized this into more specific tasks that we can address with manageably-sized PRs. The tasks are listed in the order we would perform them, though some can be done without blocking on others:

Task Issue PR
Reorganize the docs homepage menu N/A #13062
Add a separate sidebar section for labs and demo environments #14548
Add a "Get Started" section #13206 #13342 (This is an out-of-date draft that we need to update)
Add a "Learn" section
Add a "Configure Access" section (2022-06-06 edit) #13357
Split "Setup" #13359
Break up the "Enterprise" and "Cloud" sections #13361
Add a sidebar section for end users This is being added along with our Teleport Connect docs
Propose a way to organize resource service guides #13362

In tasks related to reorganizing the docs, we should try to minimize changing individual pages as much as possible. We have a lot of docs pages, so it would simplify the reorganization to move existing pages to new sections rather than rewrite our docs.

Add a "Learn" section

Before we reorganize other sections of the docs, we should move informational sections that do not include step-by-step guides or comprehensive references into a "Learn" section. This way, it will be easier to introduce, split, or merge sections having to do with step-by-step guides for specific adoption tasks.

This section can include content from these existing subsections/pages:

Add a "Get Started" section

Rather than "Home," the first link in the navigation sidebar should be "Get Started." To begin, we can add two subsections here:

While adding resources is also part of getting started, we should devote separate tasks to reorganizing the guides in "Server Access," "Application Access," etc., since there's a lot of content there.

Add a "Configure Access" section

Added 2022-06-06

Originally, I had planned to put guides related to a user's initial cluster configuration in the "Get Started" section. However, we would be placing a few subsections within this section, such as a subsection for our SSO guides. Since our navigation bar can only support two subsection levels (e.g., /docs/setup/*.mdx and /docs/setup/guides/*.mdx), this would mean that we would need to cut some guides from the nav bar.

This section will include most of the current content in the "Access Controls" section.

I propose adding these current subsections to the "Configure Access" section:

Here are some misc. guides that we should move to this section:

Split "Setup"

We should split the "Setup" section into two sections:

Break up the "Enterprise" and "Cloud" sections

Currently, our content on getting started with Teleport skews toward the Open Source edition, and users need to discover our Cloud and Enterprise guides for themselves. We should make it clear from the beginning of a user's journey through the documentation that Cloud and Enterprise are alternatives to Open Source.

Now that we can make the content of a single docs page dynamic based on the user's scope (cloud, oss, and enterprise), we should move the content from the Enterprise and Cloud sections into sections related to getting started with Teleport. Users can adjust their scope to get the right instructions for their use-case. This means that users of all editions can use the same routes through the docs site.

If we do this, we will also need to include a prominent link to an edition comparison guide, e.g., on the docs homepage.

Reorganize the docs homepage menu

Currently, the main body content of the docs home page links to sections related to individual resources (Server Access, Application Access, etc.). For users visiting the docs for the first time, there's nothing in the way of initial setup instructions.

Instead, this page should be organized to imply that there is a progression from one stage of the user's setup to the next:

Each stage can be a heading. We can include a couple of tiles for key guides in each stage.

This way, it will be clearer to readers which docs pages they should start with, and which they have in store for later.

Propose a way to organize resource service guides

Adding resources is part of getting started with Teleport, so if we are using the chronological organization of the navigation sidebar, it would make sense to add these guides to the "Getting Started" section. However, we have a lot of content in these guides, so moving all of them into a subsection of "Getting Started" could make the sidebar much harder to use.

For example, resource-specific sections have their own subsections, and our sidebar can support up to two levels of subsection headings. If we need to bump each subsection down a level, we will need to drop subsection headings from the sidebar.

I think we should reorganize our resource-specific sections last and, when the time comes, come up with a separate issue that proposes a more specific reorganization strategy.

ptgott commented 2 years ago

I think enough of this has been completed that we can consider the issue done. There are a few child issues still lingering—adding a "Learn" section and reorganizing our resource service guides—but I think it makes sense to treat these as separate issues: