Reorganize our docs to make Teleport adoption easier #12787
Comments
|
Note that this is a partial solution to #12187. We will probably also be making changes to |
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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
Backports #13062 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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
Backports #13062 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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
Backports #13062 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, it's difficult to determine what is involved in getting started with Teleport. This change organizes the docs landing page to imply that there is a progression from one stage of the user's setup to the next. See #12787 - Add headings for different stages of setting up Teleport. - Add links to a Getting Started guide for each edition that includes a "scope" query so users are given the appropriate scope (this partially addresses #12773). - Edit the initial list of Teleport benefits to be more general and encompass more functionality. - Very light copy-editing of the text in the tile lists at the bottom of the page.
One solutionAdded 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:
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" sectionBefore 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" sectionRather 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" sectionAdded 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., 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" sectionsCurrently, 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 ( 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 menuCurrently, 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 guidesAdding 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. |
|
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:
|
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.
The text was updated successfully, but these errors were encountered: