Improve Discovery troubleshooting #3218
Conversation
|
The PR preview for 4f791ca is available at theforeman-foreman-documentation-preview-pr-3218.surge.sh The following output files are affected by this PR: |
There was a problem hiding this comment.
Considering that this is a troubleshooting section (so we can expect users who are frustrated), I looked for opportunities to make the bullet points shorter. Any word you can drop counts.
On a similar note, the troubleshooting section is quite long and has many bullets. That makes it look very daunting. I wonder if you could group these bullets into some sort of categories with .Headings, perhaps based on the configuration areas you mention at the beginning of the module. That would certainly help make the whole section less intimidating because you would present it in shorter, more manageable chunks.
And on a completely different note, I would very much appreciate a lot more details on how to check for the things you're asking users to check. Including, but perhaps not limited to, what specific error messages they might see.
guides/common/modules/con_prerequisites-for-using-discovery.adoc
Outdated
Show resolved
Hide resolved
|
One more question @Lennonka Is there a specific reason why you are formally requesting a review from multiple people? I don't think a single PR needs three sets of eyes unless you expect us to, for example, review your PR from different perspectives. |
@asteflova I wanted one review from Max and one from a RH person, and Avital didn't respond. |
While these suggestions are noble, I was going mainly for structural improvements. It would take great effort to fill in all this information and I don't have the capacity for it in this PR. Thank you for your review! |
This suggestion is also part of the structural improvements that I recommend. To give a bit of background of how I approached this peer review when you requested my feedback: I checked out this PR's description where you posted a link to #3041 (in which you are asking for tips on how to structure troubleshooting content) and I also noticed that this PR is part of https://github.com/theforeman/foreman-documentation/milestone/6 (whose goal is to deliver beginner-friendly provisioning docs). So I had these two goals in mind as I was reading your changes.
It would. I think it's worth it. Provisioning is a complex area and it's reasonable to expect that users would appreciate detailed guidance when troubleshooting it. Also, keeping in mind your overall goal of delivering beginner-friendly provisioning docs, detailed troubleshooting steps are part of that goal. Giving troubleshooting content a more rigid structure (for example: Problem/Error message -- Explanation -- Solution) can actually also help with collecting the pieces of information you need: You can first create a template like that for each troubleshooting step and fill it with what you know, leaving the rest blank. Then you can share that with your SMEs, which gives them a very concrete idea of what's missing and makes it easier for them to fill those gaps in.
That is a choice that you can make as the author of this PR. In its current state, your PR doesn't really break anything (which is why I did not use GitHub's feature to request changes). However, I do think that not trying to dig deeper and research more specific, more actionable troubleshooting steps would be a missed opportunity. |
|
@asteflova I truly appreciate your suggestions. I'm choosing not to make any further enhancements at this time. We can revisit it once we have a customer request for more information in this area. With the previous improvements in the whole chapter, there should be lesser need for troubleshooting because the information is organized better. |
Co-authored-by: Maximilian Kolb <[email protected]>
Co-authored-by: Maximilian Kolb <[email protected]>
Part of Issue #3041
Please cherry-pick my commits into: