Add docs for foreman_ansible_director plugin#4730
Add docs for foreman_ansible_director plugin#4730maximiliankolb wants to merge 6 commits intotheforeman:masterfrom
Conversation
github-actions
bot
added
Needs tech review
maximiliankolb
force-pushed
the
foreman_ansible_director
branch
5 times, most recently
from
98e10f6 to
c2fbee3
Compare
This patch adds a guide to provide documentation for the Ansible Director plugin. Refs https://community.theforeman.org/t/how-to-refer-to-kebab-menus/45994/4?u=maximilian Refs https://github.com/ATIX-AG/foreman_ansible_director/ Refs https://github.com/ATIX-AG/smart_proxy_ansible_director/
maximiliankolb
force-pushed
the
foreman_ansible_director
branch
from
c2fbee3 to
d279598
Compare
All entities created by users are scoped by orgs.
| By default, {Team} supports Ansible that is packaged for the platform your {ProjectServer} or {SmartProxyServer} runs on. | ||
| If you want to configure different client platforms that rely on different Ansible or Python versions, you can use the Ansible Director plugin. | ||
| The Ansible Director plugin allows you to manage Ansible content, Ansible Execution Environments, and Ansible environments independent of your {Project} platform. | ||
|
|
||
| // TODO: Reword to better explain that you can technically use them in parallel but it's most likely not necessary. | ||
| You can use the Ansible plugin and Ansible Director plugin simultaneously on {Project} but they are unrelated. |
There was a problem hiding this comment.
Could this be split out into a separate overview-like chapter?
| @@ -0,0 +1,33 @@ | |||
| :_mod-docs-content-type: ASSEMBLY | |||
There was a problem hiding this comment.
There are a lot of sections here (15). So that made me think: How to reduce the number of modules?
The idea I had was to reconsider what the user story is. Rather than "I want to import..."/"I want to delete...", should the main focus in fact be "I want to manage and be in control of my Ansible content"? That's a tiny shift in mindset but could help redesign the procedures into something like:
- In the web UI, go to XYZ to view your current Ansible content.
- Want to add something? Go to Import Ansible content.
- Want to remove something? Go to Delete Ansible content.
- View the list of content again to check it's all to your liking now.
It could be a way to reduce the number of procedures because you'd effectively combine them into a smaller list of more wholesome procedures that cover more, but in context of what the user's actual goal is.
There was a problem hiding this comment.
This applies to some of the other assemblies as well so I'd suggest to look at options for reimagining the underlying user stories there as well.
| .Prerequisites | ||
| * Your {Project} account has a role that grants the `create_ansible_content`, `view_ansible_content`, and `view_organizations` permissions. | ||
|
|
||
| .Procedure |
There was a problem hiding this comment.
This is a very long procedure (like many of the other web UI procedures here). Downstream, we now have a (soft) limit on max 10 steps per procedure. This one is already at 10 steps. Is there a way to document fewer steps and rely on the instructions in the web UI more? In other words: what can the user figure out on their own from the interface, so that we don't have to document it explicitly? The workflow itself doesn't look too complex (it's just about filling a form...) but the procedure makes it look complex, just due to the sheer number of the steps involved.
TODOMention two roles provided by the plugin:
|
2 participants
What changes are you introducing?
This patch adds a guide to provide documentation for the Ansible Director plugin.
Why are you introducing these changes? (Explanation, links to references, issues, etc.)
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
Contributor checklists
Please cherry-pick my commits into: