There are multiple things to consider.
First, when docs team brings guides upstream, they want to do minimum possible changes so we track what was actually modified in order to have the content relevant. The most important changes in this phase are replacing Satellite with Foreman/Katello, replacing many example code, URLs and hiding irrelevant parts (subscription manager, RHEL).
What we get is a starting point we, as a community, can improve on. And this is where we at, what you see. So far, we have been adding various remarks or new content which covers some differences, including the whole Debian guide which is already amazing contribution. But I would like to stop here and think.
If you look at the current official docs as a newcomer, you are confused. Thereās Foreman, theres Katello, installations are completely different. There are many plugins which are documented on various places yet you are not given a good overview of what Forman is capable to. We fail to explain this and this new documentation could be our chance to be more opinionated.
The new generation documentation on the other hand is consistent experience. There are still gaps we can fill, particularly in describing how things work as these guides are more process oriented. Thatās where we can step in and fill in the content.
Saying that Katello is the only deployment type is definitely not a solution, hence I would like us to discuss this before we commit to any upstream-only changes in our new documentation. What we can do on multiple levels with this Foreman vs Katello problem. Unifying installers with ability to āupgradeā has been a long discussion. I believe this could be a good solution, one installation for everyone. Where we stand today can probably @ehelms or @ekohl comment on. Certificates are often major problem of this, you actually mentioned it. I am aware that we are planning some changes in this regard to solve it. Maybe moving into containers shakes everything so much that this is no longer an issue? Is that a solution? I donāt know. There are many things to consider.
Anyway, I would like to say loud that there is no pressure on anyone here for getting the documentation merged. We can take our time, our writers team will continue working in the new upstream repository, we can be closer when contributing features and users can report/fix bugs or typos more easily. In the meantime, our official documentation is still what we promote on our webpage. (You will see me often linking the new docs, but I canāt help myself - provisioning is not well covered in our official docs.)
In the end, I would love to see our new documentation to join documentation effort across most Foreman-based products. I know that every single product available out there has different setup, different installation instructions, different everything. There is undergoing change in the new docs which is called āmodularizationā. Every bit of documentation is a reusable module (think: separate file) and books are assembled from those. So there is a lot we can work with.
