Proposal: Remove App. C from "Administering Foreman" guide

Community
1

I propose removing Appendix C: Administration settings from the Administering Foreman guide for the following reasons:

  • It duplicates information that is already documented in procedures.
  • It requires constant maintenance.
4 Likes
2

+1

It doesn’t add any value to information that users can see in the web UI.

3

Also the Settings depend on the installed plugins what is not mentioned at all.

I think having this as a reference only makes sense if we can auto-generate it like we did in the old manual with the command line parameters, everything else is to much effort for to less benefit.

2 Likes
4

+1 from me too.

5

When supporting users here on Discourse I have used the reference documentation so I can link to the exact setting so I think there is value in keeping it.

Building a script to export the settings in asciidoc is not hard. I was going to say we already have it, but it looks like I never committed it. I created lib/tasks/settings.rake with the following:

namespace :settings do
  task overview: :environment do
    registry = SettingRegistry.instance
    registry.categories.each do |category, label|
      puts <<~HEADER
        = #{label} settings

        [cols="30%,30%,40%",options="header"]
        |====
      HEADER

      registry.category_settings(category).each_value do |setting|
        puts "| *#{setting.name}* | #{setting.default} | #{setting.description}"
      end
      puts "|==="
    end
  end
end

It probably needs a bit more polish and scripting to automate updates around releases.

1 Like
6

Having a list of options for a quick review without access to the web UI can be useful. Also, I don’t think the reference is available from the Hammer CLI, is it? (EDIT: Apparently it is! hammer settings list)

The point I’m trying to make is that while the lists are a (significant and annoying) maintenance burden, a reference like this is useful to have because not everyone can access the web UI from anywhere, at any time.

I recall that in the past we discussed the option of referencing the options + their definitions through linking to the code but that was deemed not very user-friendly.

I like the option of exporting the settings programmatically very much. It’s what we do with the Hammer reference right now – we recognize the value in having an online reference for Hammer commands, so we found a way to provide that to users with a script.

7

0 from RH support (I’ve checked with them.)

They are not against removing it, but we don’t know how many users have been using it. Support themselves don’t need it.

They like the idea of generating the reference programmatically.

If we decide to remove it, we should add a deprecation notice in the release notes of the preceding release.

“Just reading settings from docs would do no good if you can’t change them due to access issues.“

8

I already created Fixes #35577 - Add a settings:reference rake task by ekohl · Pull Request #9438 · theforeman/foreman · GitHub to automate it for the current website, but never really followed up on that.

9

Generating the sections with a rake task seems like a good solution.

I could check the numbers of page views for the sections, but it would be irrelevant if we are going to keep the section in and generate it automatically.

10

FYI - page visits over last 3 months for non-Red Hat visitors to the downstream Satellite Admin guide, App. C (all subsections):

  • Oct. 2025: 6.17 - 27
  • Nov. 2025: 6:17 - 10, 6.18 - 18
  • Dec. 2025: 6.17 - 9, 6.18 - 13

I could generate stats for more months and versions but I think you get the idea.

Can we generate all the Admin settings? If so, that would remove the maintenance burden completely.

11

I do like Ewoud’s idea of keeping it and automating it. In fact, I kind of assumed it was automated from the start, since I recognized the wording from reading hammer help.

I think so far everyone agrees that the manually-maintained guide is not worth keeping. So the question is do we commit the additional effort to automate it (moving the maintenance burden more to developers), or go the other direction and remove it.

12

The responsibility for updating the reference doesn’t necessarily have to move to developers as long as we have guidelines how to generate it. (Which would have to happen once per release.)

But I don’t think that the reference is a useful way of documenting the settings - they should be documented in such a way that the docs provide additional context and use cases for changing them.

2 Likes
13

This is a great point. In Settings documentation I would expect to see additional explanation and overview of things like how Settings work, the fact that they are universal (not per-user or per-org), the different ways to set them, comparison and contrast of Settings, installer options, user preferences, and other ways to set application behavior, etc. That’s the real value that documentation can provide, which is much more than just a reference.

1 Like
15

A layout that does not use tables would improve the usability of this section significantly. Bullet lists and definition lists are much easier to read. The default value of a setting could be appended to the description.