Update documentation around project use cases by aneta-petrova · Pull Request #4969 · theforeman/foreman-documentation

aneta-petrova · 2026-06-25T12:18:52Z

What changes are you introducing?

Reviewing and updating Planning guide information regarding Foreman overview and benefits. This should eventually involve:

Listing Foreman's use cases/core capabilities
* [x] Reorganizing the existing documentation that supports these use cases
* [x] Identifying which use cases are not yet described
* [x] Documenting these gaps

The PR also exposes the containerized Planning guide in navigation, with the new section on use cases being the only section included in the containerized guide. It should serve as an introduction to the project.

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

~~The goal is to concentrate this introductory information in one place and make sure it's up-to-date and aligned with the project's direction.~~

To provide a short overview of the main use cases aka 'why you should use Foreman (and Katello)'

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

Target audience: Architect

Documentation category: Discover = Orient to what the project is, what it does, and when to use it / Understand whether the project solves my problem, what it can do, and how it conceptually works

Assisted-by: Cursor, Claude

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.19/Katello 4.21
Foreman 3.18/Katello 4.20 (Satellite 6.19)
Foreman 3.17/Katello 4.19
Foreman 3.16/Katello 4.18 (Satellite 6.18; orcharhino 7.6, 7.7, and 7.8)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4; orcharhino 7.5)
We do not accept PRs for Foreman older than 3.14.

github-actions · 2026-06-25T12:22:44Z

The PR preview for aedfa00 is available at theforeman-foreman-documentation-preview-pr-4969.surge.sh

The following output files are affected by this PR:

show diff

show diff as HTML

aneta-petrova · 2026-07-10T13:32:50Z

+= {Project} use cases
+
+[role="_abstract"]
+{ProjectName} is a centralized tool for provisioning,


The AbstractLength failure is only due to conditionals. The rendered text is within the required limit.

aneta-petrova · 2026-07-10T14:07:27Z

Hi @ekohl, @ianballou, and @parthaa, can you please review this description of use cases?

ekohl

This may be a bit of a brain dump. Especially the TODOs to link guides is something you're already aware of, but it helps me to write it down.

ekohl · 2026-07-10T14:17:57Z

+
+{ProjectName} focuses on the following use cases:
+
+Provisioning::


Todo: link to the provisioning hosts guide

Just for completeness, I'll also note that concept modules can no longer include links in the module's body. Any link that we decide to add would have to go in an .Additional resources section. With that in mind, we should also make sure that .Additional resources don't just duplicate a list of guides that users can easily see at docs.theforeman.org.

You could make a point that this content should live directly on https://theforeman.org/ as well and from there point to the guides.

I could, but that wouldn't get me much closer to my goal, which is updating product documentation -- including the downstream one :)

ekohl · 2026-07-10T14:18:36Z

+This approach provides enhanced control over what software runs in your environment.
+endif::[]
+
+Security management::


Todo: link to the managing security compliance guide.

ekohl · 2026-07-10T14:18:55Z

+
+This capability enables centralized security oversight, supports incident response, and helps reduce the attack surface of your systems.
+
+Knowledge and analytics::


I wonder where we have this. In the managing hosts guide?

I suspect our guides might not always map precisely to these use cases. At least some of our guides are feature-based (content, hosts) and use cases might pull in multiple features.

Ideally, our documentation should be organized in a way that begins with the use cases as a high-level starting point (think one guide per use case), and then that would make it easy to link to docs from this section. I recognize that saying "Foreman can do this super cool thing" without clearly pointing to guidance on how to achieve it is not great, but it's at least a good first step (and IMO a very necessary thing to do in general).

I think it's been an underdeveloped area for a long time. https://github.com/theforeman/foreman_statistics was extracted from core and barely sees any activity. Perhaps the whole project should think about how we can support this use case.

Edit: https://theforeman.org/ has some things that work towards this, but I think it's outdated.

ekohl · 2026-07-10T14:19:26Z

+This knowledge helps you make informed decisions about your infrastructure and spot potential problems.
+
+ifndef::satellite[]
+Configuration management::


Todo: link to Ansible, Puppet, and Salt guides (where applicable).

ianballou · 2026-07-10T14:38:01Z

+Patch management::
+Apply updates to hosts in a consistent, scalable, and repeatable manner.
+
+{ProjectName} helps you schedule maintenance windows, test updates in staging environments, and roll out patches across your infrastructure with controlled deployment strategies.


I like this definition of Katello, I think it represents its core use cases well.

aneta-petrova · 2026-07-10T16:41:11Z

This may be a bit of a brain dump.

A good brain dump that helped me improve things, thank you.

Especially the TODOs to link guides is something you're already aware of, but it helps me to write it down.

Is this something you'd expect to see in this PR? For reasons I noted here and elsewhere (we don't have containerized guides yet, .Additional resources shouldn't duplicate a list of guides, it's tricky to map use cases to feature-based documentation), including the links wasn't on my to-do list for this PR.

Drop redundant conditionals Emphasize flexibility in provisioning over standards Drop the separate patch management use case Update non-core use cases for Satellite

ekohl · 2026-07-10T16:48:32Z

Is this something you'd expect to see in this PR? For reasons I noted here and elsewhere (we don't have containerized guides yet, .Additional resources shouldn't duplicate a list of guides, it's tricky to map use cases to feature-based documentation), including the links wasn't on my to-do list for this PR.

No. It helped me to connect things and I'd love to in the future but in the short term I don't think it's feasible.

pr-processor Bot added the Not yet reviewed label Jun 25, 2026

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 Jun 25, 2026

aneta-petrova removed 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 Jun 25, 2026

aneta-petrova force-pushed the planning-intro branch 2 times, most recently from 6c661aa to dc5d258 Compare June 25, 2026 13:33

aneta-petrova force-pushed the planning-intro branch 2 times, most recently from 9ae8ab2 to 46b32c8 Compare July 10, 2026 12:53

aneta-petrova added 2 commits July 10, 2026 14:55

Expose containerized planning guide in navigation

35c55f7

Document project use cases

f173d80

aneta-petrova force-pushed the planning-intro branch from 46b32c8 to f173d80 Compare July 10, 2026 12:55

aneta-petrova commented Jul 10, 2026

View reviewed changes

pr-processor Bot removed the Not yet reviewed label Jul 10, 2026

aneta-petrova force-pushed the planning-intro branch 4 times, most recently from 5777340 to df2d225 Compare July 10, 2026 13:51

aneta-petrova added 2 commits July 10, 2026 15:57

Expand use cases with more details

59cf6cd

Mention MCP in the list of use cases

7cd51f7

aneta-petrova force-pushed the planning-intro branch from df2d225 to 7cd51f7 Compare July 10, 2026 13:57

aneta-petrova marked this pull request as ready for review July 10, 2026 13:58

ekohl reviewed Jul 10, 2026

View reviewed changes

ianballou reviewed Jul 10, 2026

View reviewed changes

aneta-petrova force-pushed the planning-intro branch 2 times, most recently from 419abe4 to a2d99fd Compare July 10, 2026 16:16

aneta-petrova force-pushed the planning-intro branch from a2d99fd to 90f1a47 Compare July 10, 2026 16:30

Apply feedback from tech review

3fe7eb6

Drop redundant conditionals Emphasize flexibility in provisioning over standards Drop the separate patch management use case Update non-core use cases for Satellite

aneta-petrova force-pushed the planning-intro branch from 90f1a47 to 3fe7eb6 Compare July 10, 2026 16:46

Use shorter attribute after first occurence of productname

f82af61

Include config management as a high-level use case for Satellite

aedfa00

aneta-petrova force-pushed the planning-intro branch from 53580d8 to aedfa00 Compare July 10, 2026 17:05


		{ProjectName} focuses on the following use cases:

		Provisioning::

Uh oh!

Conversation

aneta-petrova commented Jun 25, 2026 • 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 Jun 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aneta-petrova commented Jul 10, 2026

Uh oh!

ekohl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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!

ekohl Jul 10, 2026 • 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aneta-petrova commented Jul 10, 2026

Uh oh!

ekohl commented Jul 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

aneta-petrova commented Jun 25, 2026 •

edited

Loading

github-actions Bot commented Jun 25, 2026 •

edited

Loading

ekohl Jul 10, 2026 •

edited

Loading