Reorganize the documentation #43376
Closed
Reorganize the documentation #43376
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
🤖 Vercel preview here: https://docs-one0pzkfg-goteleport.vercel.app/docs/ver/preview |
ptgott
force-pushed
the
paul.gottschling/2024-06-reorg
branch
from
df6eb67
to
d547b24
Compare
* Use H2s for child content This way, a user knows whether a page is a section table of contents. Stop at one child level to avoid overwhelming the user. * Use auto-generated menu pages for Database Access
* Use auto-generated menu pages for Access Controls
Introduce a generation script for table of contents pages in the docs,
i.e., pages that list the topics within a given subdirectory. This will
make it easier to:
- Carry out large-scale reorganizations of the docs, since we can
rapidly regenerate table of contents pages as we move around
directories.
- Use the navigation sidebar only for high-value links, rather than all
links, so we can create subdirectories at an arbitrary depth.
Automatically generating TOC pages ensures that all docs pages are
represented.
As a proof of concept, this change implements the auto-generation script
in the Access Controls section of the docs.
The generator considers a TOC page any page that has the same name as a
subdirectory within its current directory. It looks for the comment
`{/*TOPICS*/}` and overwrites everything below this comment with a list
of topics. The generator throws an error on `{/*TOPICS*/}` comments in
pages that don't correspond to subdirectories.
Some pages combine a list of links with lengthy explanatory text. This
change moves these into new pages called `overview.mdx` and adds more
bare-bones table of contents pages in their place.
* Use H2s for child content
This way, a user knows whether a page is a section table of contents.
Stop at one child level to avoid overwhelming the user.
Sections included in this change: - docs/pages/agents/ - docs/pages/auto-discovery/ - docs/pages/choose-an-edition/ - docs/pages/desktop-access/ - docs/pages/includes/ - docs/pages/kubernetes-access/ Other changes: - Move Helm includes out of docs/pages/kubernetes-access to match the expectations of the TOC page generator. Also move "Connect your Client" includes to docs/pages/includes. - Some pages were at the expected location of a TOC page (i.e., with the same name as a subdirectory), but included explanatory information that didn't fit the format of this kind of page. This change moves these pages to other locations as overview pages. - Update config.json.
- Server Access - Deploy a Cluster
As part of this, move the Dynamic Resources intro to an overview page, since its role is to provide context rather than a list of links. Also removes the "Management" intro page and uses the TOC page as the introduction, since the current intro page already uses a bare-bones TOC format.
As part of this, change the Machine ID Deployment intro page to an Overview page so we can turn that path into a table of contents page. Also remove a redirect so we can visit `/docs/machine-id/`.
- Application Access - Reference As part of this, move the CLI reference intro page to a separate overview page so we can turn the current intro page into a table of contents. Also move Helm reference includes to the includes directory.
Incorporate the API and Architecture sections into new docs structure. Move API guides into Admin Guides, except for the API architecture page, which belongs in Reference. This change adds an Architecture section to Reference for the API architcture guide and other architecture guides. This change also merges the API intro page and TOC page, as the intro page doesn't add much beyond the TOC. Finally, this change moves all guides in the Architecture sidebar section into `reference/architecture`.
Management subsections into References and Admin Guides depending on whether the subsection contains how-to guides or comprehensive references. Some guides (mostly in "Secure Practices") aren't how-to guides, but also aren't comprehensive lists of possible values. I've moved these into "Admin Guides". This change also tidies up the Reference and Admin Guides sections by adding subsections. This change also removes the Trusted Cluster Address Lookup page, which is a small tip that's not referred to anywhere.
All of the Deploy a Cluster section belongs in Admin Guides. Merge this section into the Admin Guides subsection for deploying a self-hosted Teleport cluster.
All guides in Agents belong in "Admin Guides". To prevent the Admin Guides table of contents page from expanding too much, this change tidies up this section by: - Adding a Configure Teleport subsection. - Adding a Protect Resources subsection. - Moving Admin Guides subsections into Day Two Operations and renaming this section Common Operations, since some operations are appropriate for "Day One". - Add a subsection re: Teleport CAs. - Moving Trusted Clusters into Protect Resources.
Reorganize the Auto-Enroll Resources and Server Access sections. Move all of Auto-Enroll Resources into Protect Resources. To accommodate more subsections of Protect Resources, add the Trusted Clusters and Labels guides to an RBAC subsection of Admin Guides. Move all of Server Access into Protect Resources except for the Server Access RBAC reference, which this change moves into the References section.
* Move "Choose an Edition" and edit nav Integrate Choose an Edition pages into the new docs organization: - Move Enterprise guides into the Self-Hosting Teleport section. - Move the cloud-hosted Teleport Getting Started guide to the root of docs/pages so we can make it the Try Out Teleport guide. - Move FAQ pagesfrom Choose an Edition and Home into a FAQ reference section. - Remove the Documentation Overview It is no longer accurate. In addition, the new Table of Contents pages provide an overview. - Remove the Teleport Cloud intro page. We're assuming that cloud-hosted Enterprise is the happy path, so remove a page that assumes users begin with Teleport Community Edition. - Remove the Choose an Edition intro. Users who want an edition comparison can use the main Teleport site. - Move External Audit Storage into the Common Operations subsection. - Move the Cloud Downloads page to the root of the docs content directory until we determine a more appropriate home. Edit the docs navigation according to the reorganization plan: - Remove all redirects. We will add new redirects based on differences between the reorganized doc paths and links in Teleport sites that depend on them. - Edit the sidebar configuration per the reorganization plan. - Ensure that pages linked to on the sidebar can be visited without runtime errors and have reasonable titles. * Respond to mmcallister feedback
This change moves most of the guides in these sections in to the Protect Resources section of Admin Guides. Some guides are more like references, though, and this change moves these guides into Reference.
Work the Application Access and Database Access sections into the new organization structure of the docs. For the most part, these sections can fit into `docs/pages/admin/guides/protect-resources`. There are some reference guides in these sections, which this change adds to a subsection of References devoted to Agent services.
This change moves most Machine ID guides into Admin Guides. Some guides belong in the References section: - Architecture - FAQ - The "Reference" subsection of Machine ID. This change also renames the Machine ID Access Guides section. This is a workaround to get this subsection to appear after the deployment guide section in the table of contents.
This contains information currently in the "Home" section of the docs. Also respond to earlier feedback on the docs reorganization: - Rename "Protect Resources" to "Enroll Resources" - Rename "CLI Reference" to "Command Line Tools" in the sidebar.
Move Access Controls giudes into References or Admin Guides, as appropriate. Also reorganizes the Admin Guides section to reduce the size of the table of contents page.
ptgott
force-pushed
the
paul.gottschling/2024-06-reorg
branch
from
d547b24
to
b4f0603
Compare
ptgott
changed the title
|
🤖 Vercel preview here: https://docs-74vu43qzj-goteleport.vercel.app/docs/ver/preview |
Move this into the new organization structure. Before this change, there were separate subsections for Policy and Access Graph. This change moves the Access Graph subsection inside the Policy section.
github-actions
bot
requested review from
ibeckermayer,
Joerger,
kimlisa,
nklaassen,
probakowski,
r0mant,
rosstimothy,
strideynet,
tigrato and
timothyb89
|
The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with |
ptgott
removed request for
r0mant,
timothyb89,
tigrato,
probakowski,
greedy52,
ibeckermayer,
strideynet,
hugoShaka,
Joerger,
nklaassen,
rosstimothy and
kimlisa
mmcallister
approved these changes
Jul 2, 2024
|
Closing to open a fresh PR for review |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Reorganize the documentation to decouple the URL path tree from the navigation sidebar.
This change makes it possible to highlight high-value pages within the sidebar and avoid overwhelming users who first visit the docs site. In future changes, we plan to make the docs search feature more prominent. The intention is for users who cannot find the content they are looking for within a featured docs page to use the search feature to find other pages.
We still want users to be able to browse all docs pages manually. To make this possible, this change introduces a comprehensive system of table of contents pages. The
yarn all-topicsscript ensures that every MDX page with the same name as a subdirectory includes a{/*TOPICS*/}placeholder, which it overwrites to include an up-to-date list of pages within the directory.This change organizes docs content according to a modified version of the popular four-part scheme: Getting Started guides, tutorials (called "Admin Guides" here), and references, which also include architecture guides. Guides for end users appear in the "User Guides" section.