Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Take a more text-based approach to docs content #15061

Closed
ptgott opened this issue Jul 29, 2022 · 1 comment · Fixed by gravitational/docs#467
Closed

Take a more text-based approach to docs content #15061

ptgott opened this issue Jul 29, 2022 · 1 comment · Fixed by gravitational/docs#467
Labels
documentation information-architecture Finding information in the docs

Comments

@ptgott
Copy link
Contributor

ptgott commented Jul 29, 2022

Details

Let's edit the content of the docs in this repo to carry out this plan to make the docs more text oriented, i.e., more akin to a book. On the docs content side, we can start by:

  • Removing Tiles from menu pages
  • Minimizing the use of Admonitions, Notices and Details boxes

We can also consider making more radical changes that will require work in gravitational/docs. We can use two book-like docs sites as models: the Postgres docs and the Django docs:

  • Include a full table of contents on the docs landing page.
  • Remove the navigation sidebar from individual docs pages. Instead, include breadcrumbs for the next/previous pages in the "book", plus links to the main table of contents and the table of contents for the page's section.

Category

  • Improve Existing
@ptgott
Copy link
Contributor Author

ptgott commented Dec 8, 2023

Need to come up with a more focused list of objectives, otherwise this issue will be outstanding forever.

@ptgott ptgott added the information-architecture Finding information in the docs label Apr 10, 2024
ptgott added a commit to gravitational/docs that referenced this issue May 31, 2024
Closes gravitational/teleport#15061

We want to encourage a more textual approach to the docs. Add this as a
general goal to the style guide. If ther eare specific violations of
this style suggestion that we want to address with documentation
efforts, linters, etc., we can plan these separately.
ptgott added a commit to gravitational/docs that referenced this issue Jun 3, 2024
Closes gravitational/teleport#15061

We want to encourage a more textual approach to the docs. Add this as a
general goal to the style guide. If ther eare specific violations of
this style suggestion that we want to address with documentation
efforts, linters, etc., we can plan these separately.
travelton pushed a commit to gravitational/docs that referenced this issue Aug 26, 2024
Closes gravitational/teleport#15061

We want to encourage a more textual approach to the docs. Add this as a
general goal to the style guide. If ther eare specific violations of
this style suggestion that we want to address with documentation
efforts, linters, etc., we can plan these separately.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation information-architecture Finding information in the docs
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant