Foreman has had links in the UI to documentation with information on how to use it. Now I wonder if we should keep this feature. Since there is no tracking in Foreman, I’d like to ask users here.
The only one I use regularly is the one to the template dsl. The one to apidoc I do not use because I type it. The new one for updates I always forget and visit the page directly. So I am not sure if I would use the links more often, if they were more prominent and all over the place or if this would be disturbing then!
I realize I should have qualified this better.
There are documentation links within the application itself (template DSL, apidoc) but I’m not talking about those. I’m talking about the external links. Those that point to Index of /manuals or https://docs.theforeman.org/.
It feels to me that the manual/docs don’t really match up to the UI anymore and I’m wondering if we should remove them instead of fixing them up.
In parallel I’ve been thinking if we can perhaps include more in-application help texts so we don’t need external docs to understand the UI.
I personally don’t use the documentation buttons (unless I want to test if I broke them 
), but I always thought that they provide value to users because they’re referring users to specific parts of the huge guides.
Maintenance wise, those buttons are kinda expensive.
Would you like to talk about what type of maintenance are you struggling with? Regardless the original question, I think we should reduce the burden.
I am pretty sure it won’t be feasible. Our UI requires context to understand a specific switch/knob/field. I think the documentation currently provides this context. Otherwise we risk documentation that will state the obvious and sounds more like “it’s a button, you can push it”, which is not that helpful.
I often struggled to find the anchors in code, esp. for upstream. For downstream, I know that each downstream product has a plugin which basically contains a list of anchors that might need adjustments after changing an anchor in foreman-documentation.
But for upstream foreman, katello, and other plugins such as foreman_ansible, it’s more difficult for me. Maybe it has gotten better recently?
$ rg documentation_button
app/views/ansible_roles/index.html.erb
4: documentation_button('Managing_Configurations_Ansible', type: 'docs', chapter: 'Importing_Ansible_Roles_and_Variables_ansible') %>
app/views/ansible_variables/index.html.erb
5: documentation_button('Managing_Configurations_Ansible', type: 'docs', chapter: 'Importing_Ansible_Roles_and_Variables_ansible') %>
app/views/ansible_variables/_fields.erb
68: <h2><%= _("Specify Matchers") %> <%= documentation_button('Managing_Configurations_Ansible', type: 'docs', chapter: 'Overriding_Ansible_Variables_in_foreman_ansible') %></h2>
If every plugin did this, then I would feel encouraged to investigate those buttons more regularly.
In the UI it isn’t very consistent either, but there you can look for getDocsURL and getManualURL.
If we’d ever finish the migration of the documentation, we should get rid of the old getManualURL.
Now that people had some time to vote, I’ll share what my thoughts around this are. I didn’t want to lead people in a certain direction.
My fear is also that they style of documenting doesn’t match what is actually documented. For example, the page overview of operating systems links to Foreman :: Manual. On docs.theforeman.org it could link to Provisioning hosts but is that the same? It doesn’t describe auto-created operating systems so the overall concept isn’t described. And is our form really that bad that we need 5 pages of documentation on how to use it? I’d love to get rid of the examples for Debian 12/13/Ubuntu 24.04/Ubuntu 26.04 and instead enhance the UI to quickly prefill it with well known OSes.
If people use these buttons, it can make sense to create dedicated documentation on how to use the screen and what to expect with it. If they don’t, it’s a wasted effort. Wouldn’t be better to include more of the context in the application itself. The downside is that you can’t easily link to it when you’re helping users, for example here on Discourse. People can’t learn ahead of time what to expect.
I think that we are facing the difference between how our UI is designed and how our documentation leads the user: the documentation is more task oriented, it answers the question “how do I do X”, but the our UI is more like a REST endpoint, it answers the question “How do I mutate this specific object”.
This leads to many-to-many relationships between the documentation and the UI. I can see it as the same page is used for multiple use cases (e.g. the hosts page is used by both “I want to provision a host” and “I want to manage content for a specific host” use cases) and one use case touches multiple pages (e.g. “I want to provision a host” will touch the Operating system details page and a host details page).
Yes, it creates problems with having a single docs link on a page. On the other hand maybe we should leverage this situation and create some sort of “reverse index” pages that will be the landing point, and they in turn will show to the user a choice of use cases that involve that page.