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.

Sign up for GitHub

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

Jump to bottom

Refactor cloud-linux page #40636

Closed
wants to merge 14 commits into from
Closed

Refactor cloud-linux page #40636

wants to merge 14 commits into from

Conversation

bernardjkim
Copy link
Contributor

This PR refactors the cloud-linux upgrade documentation page.

The changes attempt to simplify the instructions for updating an agent. The documentation now makes a clear distinction between automatic and manual updates, and guides/recommends users to enable automatic updates.

@bernardjkim bernardjkim added documentation no-changelog Indicates that a PR does not require a changelog entry automatic-upgrades labels Apr 17, 2024
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-9o9roqz6a-goteleport.vercel.app/docs/ver/preview

Base automatically changed from bernard/automatic-updates-docs to master April 22, 2024 18:21
@bernardjkim bernardjkim force-pushed the bernard/refactor-cloud-linux-docs branch 2 times, most recently from 6b1f08a to e2d2a9b Compare April 23, 2024 20:02
@bernardjkim bernardjkim force-pushed the bernard/refactor-cloud-linux-docs branch from e2d2a9b to 92a4d5a Compare April 23, 2024 20:04
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-d6kd9kmy9-goteleport.vercel.app/docs/ver/preview

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-rvzx3kspu-goteleport.vercel.app/docs/ver/preview

@bernardjkim bernardjkim force-pushed the bernard/refactor-cloud-linux-docs branch from 92a4d5a to 757b7e0 Compare April 23, 2024 20:33
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-1hvoo8egw-goteleport.vercel.app/docs/ver/preview

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-g9qj00e1u-goteleport.vercel.app/docs/ver/preview

@bernardjkim bernardjkim marked this pull request as ready for review April 24, 2024 01:02
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-nfs6nc14z-goteleport.vercel.app/docs/ver/preview

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-nsecac022-goteleport.vercel.app/docs/ver/preview

@bernardjkim
Copy link
Contributor Author

@ptgott Is this something new that is being enforced?

[vale] reported by reviewdog 🐶
[structure.architecture-h2] In a how-to guide, the first H2-level section must be called `## How it works`.

It doesn't look like we use this in our other pages.

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-ezh3ftxpq-goteleport.vercel.app/docs/ver/preview

@ptgott
Copy link
Contributor

ptgott commented Apr 26, 2024

@bernardjkim This is something we're rolling out to address gaps in architectural information in our how-to guides. There are examples in the Database Access guides in v16 of the docs.

@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-ay89kww83-goteleport.vercel.app/docs/ver/preview

@bernardjkim bernardjkim requested a review from ptgott April 26, 2024 23:14
@github-actions GitHub Actions
Copy link

🤖 Vercel preview here: https://docs-ggimiwb24-goteleport.vercel.app/docs/ver/preview

@ptgott
Copy link
Contributor

ptgott commented May 1, 2024

I'm looking into further simplifications on this branch. The approach I'm trying out is to:

  • Include a single how-to guide for setting up automatic agent updates on Kubernetes and Linux servers (the happy path we want to plan for most users)
  • For all other use cases, include a comprehensive reference guide that also explores edge cases for setting automatic updates, including self-hosted automatic updates.

This way, we can remove a lot of the repetition between our how-to guides and provide a home for edge case and troubleshooting info. I've moved information into the reference, but need to give the reference a clearer structure.

@bernardjkim
Copy link
Contributor Author

Yeah, I like the approach of using a single guide with a happy path that most users should follow and then having a second reference will the edge cases.

If you want to make a follow up PR with your additional changes, we can continue discussion there and close this one.

@ptgott ptgott mentioned this pull request May 2, 2024
Closed
@ptgott
Copy link
Contributor

ptgott commented May 2, 2024

Opened a PR against this branch here: #41160

@bernardjkim
Copy link
Contributor Author

Closing in favor of #41160

@bernardjkim bernardjkim closed this May 2, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@hugoShaka hugoShaka Awaiting requested review from hugoShaka

@fheinecke fheinecke Awaiting requested review from fheinecke

@fspmarshall fspmarshall Awaiting requested review from fspmarshall

@r0mant r0mant Awaiting requested review from r0mant

@tigrato tigrato Awaiting requested review from tigrato

@xinding33 xinding33 Awaiting requested review from xinding33

@zmb3 zmb3 Awaiting requested review from zmb3

@ptgott ptgott Awaiting requested review from ptgott

Assignees
No one assigned
Labels
automatic-upgrades documentation no-changelog Indicates that a PR does not require a changelog entry size/sm
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@bernardjkim @ptgott