Triaging documentation PRs and issues. For details, ask in the Foreman docs Matrix chat .
Agenda: Can we add a step to update Hammer CLI reference to the release workflow?
- Instructions for updating the Hammer CLI reference: foreman-documentation/hammer_cli_reference at master · theforeman/foreman-documentation · GitHub
- In 3.13, we seem to have forgotten about it and the reference remained empty: Using the Hammer CLI tool
- Release schedule where we could add a bullet point to prevent this in the future: theforeman-rel-eng/procedures/foreman/branch.md.erb at master · theforeman/theforeman-rel-eng · GitHub
FYI @ekohl and @maximilian
1 Like
Agenda: Discuss dynamic customizable documentation wizard (Build a dynamic customizable documentation wizard by ekohl · Pull Request #3741 · theforeman/foreman-documentation · GitHub)
1 Like
A few notes from the Hammer CLI reference discussion:
- Our options for what to provide to document Hammer CLI:
- No docs, just tell users to look at the --help output. This is not what we prefer because providing the reference to users without access to a Foreman machine is useful.
- Provide the guide but only for stable branches.
- Provide the guide for nightly (and keep it up-to-date with any changes to Hammer) and stable branches. This is what we prefer but we want automation to enable it.
- Other questions that were asked:
- Which plugins should we include in the Hammer CLI reference?
- Should we include the Hammer maintainer in the process of updating the guide?
- Next step: Track this in an issue in foreman-documentation.
A few notes from the Doc wizard discussion:
- Demo of the PR
- Our options:
- Replace existing static installation guides with the dynamic wizard.
- Provide the dynamic wizard in addition to existing guides.
- Should the wizard be generated for doc PR previews? Currently, each PR includes previews of the static guides affected by the changes in that PR.
- Should we implement the wizard for other guides? Either no, or at least not right now: We should limit the scope to installation to see how well it works.
- One of the benefits is that it would help make guides smaller, which is a common user pain point.
- Next step: Further refine the PR and merge sooner rather than later to have something tangible to try and improve on.
1 Like
I see currently two similar cases: Installer Options and API
Both we have only in an older form of documentation. The Installer Options list only those of Foreman which includes of course many plugins, for the API we have one Foreman only and one Foreman+Katello.
My hope would be to have a consistent decision for this in my eyes similar references, so it is easy to understand and explain what you see and why. Then it would also be easy to know when to look at an running environment instead of the reference.
1 Like
RE Hammer CLI reference docs: I looked into installing Hammer CLI in a container: the installation works but it still requires a separate Foreman/Katello instance. I assume that we could handle this via Hammer CLI config.
PR 3789 in foreman-documentation
Right now, I struggle to see if this improves our process much. Do you see any benefit in doing this?
- Should I finish my upstream PR to write a config, extend the
Makefile, and write some docs on how to use it? - Should I investigate installing Foreman/Katello within the container?
- Am I forgetting something from your last discussion?
cc @ekohl