search

theforeman / foreman-documentation

Documentation for the Foreman Project and its ecosystem
https://docs.theforeman.org
Creative Commons Attribution Share Alike 4.0 International
21 stars 95 forks source link

Move troubleshooting section to a better place #1191

Open ianballou opened 2 years ago

ianballou commented 2 years ago

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.

asteflova commented 6 months ago

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.

asteflova commented 6 months ago

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.