Bug 2182276

Summary: [RFE] Beginner-friendly provisioning guide
Product: Red Hat Satellite Reporter: Leos Stejskal <lstejska>
Component: ProvisioningAssignee: Zuzana Lena Ansorgova <zuansorg>
Status: ASSIGNED --- QA Contact: Satellite QE Team <sat-qe-bz-list>
Severity: medium Docs Contact:
Priority: high    
Version: UnspecifiedCC: lstejska, saydas, sshtein, zuansorg
Target Milestone: UnspecifiedKeywords: Documentation, FutureFeature, Triaged
Target Release: Unused   
Hardware: Unspecified   
OS: Unspecified   
Whiteboard:
Fixed In Version: Doc Type: If docs needed, set a value
Doc Text:
Story Points: ---
Clone Of: Environment:
Last Closed: Type: Bug
Regression: --- Mount Type: ---
Documentation: --- CRM:
Verified Versions: Category: ---
oVirt Team: --- RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: --- Target Upstream Version:
Embargoed:

Description Leos Stejskal 2023-03-28 05:06:41 UTC
Document URL: 
https://access.redhat.com/documentation/en-us/red_hat_satellite/6.12/html/provisioning_hosts/index

Section Number and Name: 
Provisioning Hosts

Describe the issue: 
Current provisioning documentation contains much information that could be overwhelming for new Satellite users or someone who is new to the provisioning. I know that we expect from our customers some technical-level knowledge before they’ll start using Satellite provisioning, but nevertheless, I still believe that having some introduction and easier-to-understand documentation would benefit significantly to our customers.

Right now with current documentation, users may try every provisioning method that is mentioned in the documentation, making tons of configuration changes, troubleshooting, and trying just to see what might be the best provisioning method for them.

Having documentation that will guide the user through all provisioning methods, and shows them the comparison and differences between them can greatly benefit the user and in the end, save our support team some time with troubleshooting and answering questions.


Suggestions for improvement: 
1. Introduction to provisioning
Document where we will describe the basics, methods that can be used in the Foreman/Satellite scope, explanation of terms that we used, and so on.
There is an Intro section right now, but that's not anywhere near what it could be.

2. Comparison table of provisioning methods
Table from where users can easily see what provisioning method is the best one for them and their environment.

See the upstream post & (outdated) Satellite KC:
https://community.theforeman.org/t/provisioning-methods-comparison-table/32953/2
https://access.redhat.com/solutions/2674001

3. Split provisioning guide by provisioning methods
It’s simple: One guide = One provisioning method, don't mix them together.

4. Debugging provisioning

As an example see the upstream post:
https://community.theforeman.org/t/debugging-provisioning/32952


I realize that this is a big change and will require a lot of effort, doing all of these changes in one PR is not a good idea, I wanted mainly to draft the whole effort so the goal is clear and it’s known what has to be done. I offer my full support for the technical part of the documentation, feel free to reach me