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

Move troubleshooting section to a better place #1191

Open
ianballou opened this issue Mar 29, 2022 · 2 comments
Open

Move troubleshooting section to a better place #1191

ianballou opened this issue Mar 29, 2022 · 2 comments

Comments

@ianballou
Copy link
Contributor

The troubleshooting section (https://docs.theforeman.org/nightly/Installing_Server/index-katello.html#Troubleshooting_foreman) is currently tucked into the installation guide. It would probably be better to have a separate section of the documentation entirely for troubleshooting.

@Lennonka Lennonka changed the title Move troubleshooting section to its own page Move troubleshooting section to a better place May 16, 2024
@aneta-petrova
Copy link
Member

The anchor #Troubleshooting_foreman no longer exists, but assuming this issue is about appendices Troubleshooting DNF modules and Troubleshooting sync errors:

Separating troubleshooting information from the rest of documentation is generally not a good idea. This is because troubleshooting steps are most useful when users see them right when they encounter the issue. For example, one of the troubleshooting steps in Troubleshooting sync errors reads:

"[Errno 1] Operation not permitted: …​" during repository syncing
# chown --recursive pulp.pulp /var/lib/pulp/media/

This would be most effective when included within a procedure that describes syncing repositories, under a .Troubleshooting subheading as described in the mod docs guide.

@aneta-petrova
Copy link
Member

After checking the current version of the mod docs guide, I can see that the guidance for including troubleshooting information has changed several months ago. The guide now seems to prefer creating separate troubleshooting modules although the wording is not entirely decisive.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants