search

theforeman / foreman-documentation

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

Move "Administering with Ansible" into "Administering {Project}"? #2076

Open maximiliankolb opened 1 year ago

maximiliankolb commented 1 year ago

Hi.

I've started working on "Configuring managed hosts using Ansible" and came across https://docs.theforeman.org/nightly/Administering_with_Ansible/index-katello.html which is pretty short. Is anyone planing on extending this with more content?

I feel like so far, we've always had procedures with different way, be it GUI, API, or CLI, in the same guides. I assume the same goes for using FAM/Foreman Ansible collection. If there are no plans to extend this guide, I lean towards integrating it into "Administering_Project". If not, we should at least add it to the navigation.

Lennonka commented 1 year ago

No immediate plans to extend it. I agree with moving it inside Administering Project. Good thinking!

maximiliankolb commented 1 week ago

docs triage: @apinnick the guide linked above is pretty short. Should we move it? Extend it?

related: managing orgs/locs is a separate guide too. cc @asteflova

asteflova commented 1 week ago

related: managing orgs/locs is a separate guide too. cc @asteflova

I'm currently working on redesigning the orgs/locs documentation (no PR yet). I wasn't aware of the fact that a separate guide exists upstream, I'll make sure to read it and take it into account. Right now, it looks like some of the information in that guide overlaps with Foreman deployment planning (for example: concept explanations and usage examples) and some is actually overdocumented UI (for example: creating/deleting org/loc). Another part of the puzzle is the deployment examples and best practices in SOE.

Therefore, I'm not entirely convinced that a heavily feature-based guide like Managing Organizations and Locations is of much help. This is because none of the information included in the short Orgs/Locs guide seems to address the confusion users feel with regards to orgs/locs (example here and here). Figuring out how to create an organization and a location is easy; the tricky part is figuring out how to connect them to get the most out of them and how to tailor them to one's environment needs -- and that's a good fit for Foreman deployment planning.

But there are just my preliminary thoughts. I'm sharing them in early stages just in case anyone wants to correct me before I commit to these ideas too strongly :) I'm also wondering if perhaps we need a separate upstream issue for documenting orgs/locs (I only have one downstream).