Comply with DITA - Using Hammer - missing abstracts #4401

Lennonka · 2025-10-22T00:11:57Z

What changes are you introducing?

Adding short descriptions to Hammer cheat sheet reference modules where previously missing

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

DITA compliance

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

These abstracts were more-or-less AI generated.
This is the last PR for Hammer CLI guide, hopefully!

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.16/Katello 4.18 (Satellite 6.18)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
Foreman 3.13/Katello 4.15 (EL9 only)
Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
Foreman 3.10/Katello 4.12
Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
We do not accept PRs for Foreman older than 3.9.

github-actions · 2025-10-22T00:17:53Z

The PR preview for f353323 is available at theforeman-foreman-documentation-preview-pr-4401.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

maximiliankolb

Overall, I am not the biggest fan of "Learn ...".

maximiliankolb · 2025-10-22T07:10:15Z

guides/common/modules/ref_activation-keys.adoc


+[role="_abstract"]
+Learn the Hammer CLI commands for creating activation keys and adding subscriptions in {ProjectName}.
+You use these commands to manage activation keys that automatically configure systems during registration.


Suggested change

You use these commands to manage activation keys that automatically configure systems during registration.

You use these commands to manage activation keys that automatically configure hosts during registration.

IMO "configure hosts" is a bit of a stretch. Configuring what? subscription-manager uses AK (and CV envs) to setup content that hosts can consume.

Refs https://docs.theforeman.org/nightly/Managing_Hosts/index-katello.html#registering-a-host_managing-hosts

maximiliankolb · 2025-10-22T07:11:22Z

guides/common/modules/ref_content-life-cycles.adoc

 == Content life cycles

+[role="_abstract"]
+Learn the Hammer CLI commands for managing lifecycle environments and content views in {ProjectName}.


Suggested change

Learn the Hammer CLI commands for managing lifecycle environments and content views in {ProjectName}.

Learn the Hammer CLI commands for managing content views in lifecycle environments in {ProjectName}.

maximiliankolb · 2025-10-22T07:12:05Z

guides/common/modules/ref_content-life-cycles.adoc


+[role="_abstract"]
+Learn the Hammer CLI commands for managing lifecycle environments and content views in {ProjectName}.
+You use these commands to control content promotion and version management across environments.


Suggested change

You use these commands to control content promotion and version management across environments.

You use these commands to promote content across lifecycle environments.

maximiliankolb · 2025-10-22T07:12:23Z

guides/common/modules/ref_errata.adoc


+[role="_abstract"]
+Learn the Hammer CLI commands for managing security updates and patches in {ProjectName}.
+You use these commands to list, inspect, and apply errata to keep your systems secure and up-to-date.


Suggested change

You use these commands to list, inspect, and apply errata to keep your systems secure and up-to-date.

You use these commands to list, inspect, and apply errata to keep your hosts secure and up-to-date.

maximiliankolb · 2025-10-22T07:13:59Z

guides/common/modules/ref_general-information.adoc

+Learn essential information for using Hammer CLI in {ProjectName} effectively.
+You need to understand authentication, help options, and organization requirements before executing commands.


Suggested change

Learn essential information for using Hammer CLI in {ProjectName} effectively.

You need to understand authentication, help options, and organization requirements before executing commands.

There are certain options for using Hammer CLI in {ProjectName} that apply to all commands, including authentication and getting help.

maximiliankolb · 2025-10-22T07:15:35Z

guides/common/modules/ref_hosts.adoc

+Learn the Hammer CLI commands for managing hosts, host groups, and remote job execution in {ProjectName}.
+You use these commands to create and configure systems, organize them into groups, and execute tasks remotely.


Suggested change

Learn the Hammer CLI commands for managing hosts, host groups, and remote job execution in {ProjectName}.

You use these commands to create and configure systems, organize them into groups, and execute tasks remotely.

Learn the Hammer CLI commands for managing hosts, host groups, and remote job execution in {ProjectName}.

You use these commands to configure host group and to create hosts.

IMO organizing them into groups would be host collections. host group are more like blueprints.

maximiliankolb · 2025-10-22T07:16:22Z

guides/common/modules/ref_orgs-locs-and-repos.adoc


+[role="_abstract"]
+Learn the Hammer CLI commands for managing organizations, locations, and repositories.
+You use these commands to structure your environment and manage content synchronization.


Suggested change

You use these commands to structure your environment and manage content synchronization.

maximiliankolb · 2025-10-22T07:17:06Z

guides/common/modules/ref_provisioning-environments.adoc


+[role="_abstract"]
+Learn the Hammer CLI commands for creating provisioning infrastructure components in {ProjectName}.
+You use these commands to set up domains, subnets, compute resources, and templates for automated system deployment.


Suggested change

You use these commands to set up domains, subnets, compute resources, and templates for automated system deployment.

You use these commands to set up domains, subnets, compute resources, and templates for automated host provisioning.

IMO it's nice if we stick closer to the name of the guide & avoid using different terminology.

maximiliankolb · 2025-10-22T07:18:33Z

guides/common/modules/ref_tasks.adoc

out of scope: https://docs.theforeman.org/nightly/Hammer_CLI/index-katello.html#tasks looks off. IMO there should be a second row starting with "Monitor progress...".

aneta-petrova

Overall, I am not the biggest fan of "Learn ...".

I second that sentiment. IMO we should consider phrasing like "Learn [...]" or similar as self-referential text: It's not providing much value because of course users read docs to learn things ;) (EDIT: Or, to be clearer, they already know they're learning.) @Lennonka since this was AI-generated or AI-assisted, could you please look into tweaking your prompt?

Lennonka added this to the Prepare for DITA migration (RH) milestone Oct 22, 2025

pr-processor bot added the Not yet reviewed label Oct 22, 2025

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Oct 22, 2025

Comply with DITA - add missing abstracts

63f061f

Lennonka force-pushed the comply-dita-using-hammer-missing-abstracts branch from 20887fa to 63f061f Compare October 22, 2025 00:13

Lennonka removed Needs tech review Requires a review from the technical perspective Needs testing Requires functional testing labels Oct 22, 2025

Lennonka marked this pull request as draft October 22, 2025 00:23

Mention ProjectName

f353323

Lennonka marked this pull request as ready for review October 22, 2025 00:37

maximiliankolb reviewed Oct 22, 2025

View reviewed changes

pr-processor bot removed the Not yet reviewed label Oct 22, 2025

aneta-petrova requested changes Oct 22, 2025

View reviewed changes

pr-processor bot added the Waiting on contributor Requires an action from the author label Oct 22, 2025

	You use these commands to manage activation keys that automatically configure systems during registration.
	You use these commands to manage activation keys that automatically configure hosts during registration.

	Learn the Hammer CLI commands for managing lifecycle environments and content views in {ProjectName}.
	Learn the Hammer CLI commands for managing content views in lifecycle environments in {ProjectName}.

	You use these commands to control content promotion and version management across environments.
	You use these commands to promote content across lifecycle environments.

	You use these commands to list, inspect, and apply errata to keep your systems secure and up-to-date.
	You use these commands to list, inspect, and apply errata to keep your hosts secure and up-to-date.

		Learn essential information for using Hammer CLI in {ProjectName} effectively.
		You need to understand authentication, help options, and organization requirements before executing commands.

	Learn essential information for using Hammer CLI in {ProjectName} effectively.
	You need to understand authentication, help options, and organization requirements before executing commands.
	There are certain options for using Hammer CLI in {ProjectName} that apply to all commands, including authentication and getting help.

		Learn the Hammer CLI commands for managing hosts, host groups, and remote job execution in {ProjectName}.
		You use these commands to create and configure systems, organize them into groups, and execute tasks remotely.

	You use these commands to set up domains, subnets, compute resources, and templates for automated system deployment.
	You use these commands to set up domains, subnets, compute resources, and templates for automated host provisioning.

Comply with DITA - Using Hammer - missing abstracts #4401

Are you sure you want to change the base?

Comply with DITA - Using Hammer - missing abstracts #4401

Uh oh!

Conversation

Lennonka commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What changes are you introducing?

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

Uh oh!

github-actions bot commented Oct 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aneta-petrova left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Lennonka commented Oct 22, 2025 •

edited

Loading

github-actions bot commented Oct 22, 2025 •

edited

Loading

aneta-petrova left a comment •

edited

Loading