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

[docs] Add Troubleshooting topic to documentation #24601

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

steveburnett
Copy link
Contributor

@steveburnett steveburnett commented Feb 20, 2025

Description

Add a new Troubleshooting top-level topic to the Presto documentation, and (as the first entries in the topic) add a set of problem-solution pairs for deploying Presto to a sub-page in a new directory.

Motivation and Context

The idea of a troubleshooting Presto topic for the documentation has been discussed for a long time. Recently a coworker asked me for help installing Presto because they had followed the documentation in Deploying Presto and they encountered problems. I noticed that I had personally experienced each of his problems myself, and that the Presto doc addressed none of these.

I could have added these errors and their problems to Deploying Presto, but took this set of problem-solution pairs as an opportunity to propose the creation of a troubleshooting topic in the documentation.

Like the Presto C++ top-level documentation topic introduced in #21953, this PR creates the doc framework for troubleshooting content and provides a place in the Presto doc for similar content to be added over time. Additional content should not be added in this PR and is welcome as future PRs.

Impact

Readers can find solutions to problems presented in a format that describes the error they encounter, then (if one exists) a recommended fix for their problem.

Test Plan

Local doc builds.

Screenshots

Troubleshooting index page
Screenshot 2025-02-20 at 3 02 12 PM

Deploying Presto sub-page in the Troubleshooting section
Screenshot 2025-02-20 at 3 02 28 PM

Contributor checklist

  • Please make sure your submission complies with our contributing guide, in particular code style and commit standards.
  • PR description addresses the issue accurately and concisely. If the change is non-trivial, a GitHub Issue is referenced.
  • Documented new properties (with its default value), SQL syntax, functions, or other functionality.
  • If release notes are required, they follow the release notes guidelines.
  • Adequate tests were added if applicable.
  • CI passed.

Release Notes

Please follow release notes guidelines and fill in the release notes below.

== RELEASE NOTES ==

General Changes
* Add :doc:`../troubleshoot` topic to the Presto documentation. 

@steveburnett steveburnett self-assigned this Feb 20, 2025
@steveburnett steveburnett requested review from elharo and a team as code owners February 20, 2025 20:21
@prestodb-ci prestodb-ci added the from:IBM PR from IBM label Feb 20, 2025
@prestodb-ci prestodb-ci requested review from a team, BryanCutler and ShahimSharafudeen and removed request for a team February 20, 2025 20:21
@github-actions github-actions bot added the docs label Feb 20, 2025
Copy link
Contributor

@BryanCutler BryanCutler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @steveburnett , this looks like a great idea to me. It's nice to have some common troubleshooting in official docs. I just had some minor suggestions.

@steveburnett
Copy link
Contributor Author

@yhwang and @kiersten-stokes - I've invited you as reviewers because I would like your advice on the content in the answer of the section "Error: VM option ‘UseG1GC’ is experimental" in the deploy.rst file.

The answer I have was what I came up with, and it worked, but I hope you can either improve my answer or suggest a better and entirely different solution to this error.

BryanCutler
BryanCutler previously approved these changes Feb 21, 2025
Copy link
Contributor

@BryanCutler BryanCutler left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, just want to make sure the last solution is clear

@steveburnett
Copy link
Contributor Author

LGTM, just want to make sure the last solution is clear

Revised and updated PR, please re-review when you have time.

Copy link
Contributor

@kiersten-stokes kiersten-stokes left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will be a great add to the docs! And the current wording makes sense to me

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs from:IBM PR from IBM
Projects
Status: 👀 Review
Development

Successfully merging this pull request may close these issues.

5 participants