Skip to content

OBSDOCS-3718: Restructure Administer category per JTBD definitions - #117401

Open
johnwilkins wants to merge 1 commit into
openshift:standalone-logging-docs-mainfrom
johnwilkins:OBSDOCS-3718
Open

OBSDOCS-3718: Restructure Administer category per JTBD definitions#117401
johnwilkins wants to merge 1 commit into
openshift:standalone-logging-docs-mainfrom
johnwilkins:OBSDOCS-3718

Conversation

@johnwilkins

@johnwilkins johnwilkins commented Aug 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Restructures the Administer category based on official JTBD category definitions, moving Uninstall to Install and consolidating Scheduling and Alerts into Administer.

Key Changes

Categories Restructured

  • ❌ Deleted: "Logging alerts" category
  • ❌ Deleted: "Scheduling resources" category
  • ✅ Updated: Install category (added 3 Uninstall assemblies)
  • ✅ Repurposed: Administer category (new content: Scheduling + Alerts)

Assemblies Moved (7 total)

Uninstall (3): administering/ → installing/

  • uninstall-the-logging-operator.adoc
  • uninstall-the-loki-operator.adoc
  • uninstall-the-uiplugin.adoc

Alerts (3): logging_alerts/ → administering/

  • default-logging-alerts.adoc → understand-default-logging-alerts.adoc
  • custom-logging-alerts.adoc → configure-custom-logging-alerts.adoc
  • configuring-loki-log-based-alerts.adoc → configure-log-based-alerts.adoc

Scheduling (1): scheduling_resources/ → administering/

  • scheduling-logging-resources.adoc → schedule-logging-resources.adoc

Assembly Renaming

All renamed assemblies updated with:

  • Imperative tone titles
  • Anchor IDs matching new filenames
  • Context variables matching new filenames

Cross-References Updated

  • troubleshooting/troubleshoot-logging-alerts.adoc (2 xrefs)
  • administering/configure-log-based-alerts.adoc (2 xrefs)

Rationale

Based on the official "Product documentation categories" document:

Install Includes Uninstall

"Installation procedures, cluster creation, prerequisites verification, installer workflows, post-install checks, and uninstalling procedures."

Install is the full lifecycle category for getting the product in/out of your environment.

Administer is Day-2 Operations

"Operate and manage the product on an ongoing basis. Keep the product healthy, secure, and performing well in production."

  • Scheduling resources = Day-2 operational management (controlling where pods run)
  • Alerts = Managing logging platform health (not observing applications)

Why Not "Observe"?

The Observe category is for using logging to observe applications. Alerts for OpenShift Logging are about managing the logging platform itself, which is administration.

Final Structure

Install (10 assemblies)

  1. Installation overview
  2. Verify cluster prerequisites
  3. Configure object storage for LokiStack
  4. Install the Loki Operator
  5. Install the Red Hat OpenShift Logging Operator
  6. Install the Cluster Observability Operator
  7. Create the LokiStack
  8. Uninstall the Red Hat OpenShift Logging Operator ← NEW
  9. Uninstall the Loki Operator ← NEW
  10. Uninstall the UIPlugin ← NEW

Administer (4 assemblies)

  1. Schedule logging resources ← MOVED from Scheduling resources
  2. Understand default logging alerts ← MOVED from Logging alerts
  3. Configure custom logging alerts ← MOVED from Logging alerts
  4. Configure log-based alerts ← MOVED from Logging alerts

Troubleshoot (no changes)

  • Troubleshoot logging alerts (already here - reactive problem-solving)

Validation

  • ✅ Prow smoke test passed
  • ✅ All xrefs resolve correctly
  • ✅ Git history preserved with git mv
  • ✅ Imperative tone compliance
  • ✅ Anchor IDs match filenames

Files Changed

  • 9 files modified
  • 7 assemblies moved
  • 4 assemblies renamed
  • 2 categories dissolved
  • Topic map updated

Signed-off-by: John Wilkins jowilkin@redhat.com

@johnwilkins @claude
OBSDOCS-3718: Restructure Administer category per JTBD definitions
cce8161 
- Move Uninstall assemblies from Administer to Install (3 assemblies)
  Per official JTBD category definition, Install includes "uninstalling procedures"
- Move Scheduling assembly from scheduling_resources/ to Administer (1 assembly)
  Day-2 operational management task
- Move Alerts assemblies from logging_alerts/ to Administer (3 assemblies)
  Managing logging platform health (not observing applications)
- Dissolve "Logging alerts" category
- Dissolve "Scheduling resources" category
- Update all cross-references to reflect new paths

Category rationale:
- Install: Full lifecycle (prerequisites → install → uninstall)
- Administer: Day-2 operations (scheduling, alerts)
- Troubleshoot: Reactive problem-solving (already has troubleshoot-logging-alerts)

Assembly changes:
- Renamed: scheduling-logging-resources → schedule-logging-resources
- Renamed: default-logging-alerts → understand-default-logging-alerts
- Renamed: custom-logging-alerts → configure-custom-logging-alerts
- Renamed: configuring-loki-log-based-alerts → configure-log-based-alerts
- Updated titles to imperative tone
- Updated anchor IDs to match new filenames

Signed-off-by: John Wilkins <jowilkin@redhat.com>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@openshift-ci-robot openshift-ci-robot added the jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. label Aug 6, 2026
@openshift-ci-robot

openshift-ci-robot commented Aug 6, 2026 •
edited by openshift-ci Bot
Loading

Copy link
Copy Markdown

@johnwilkins: This pull request references OBSDOCS-3718 which is a valid jira issue.

Details

In response to this:

Summary

Restructures the Administer category based on official JTBD category definitions, moving Uninstall to Install and consolidating Scheduling and Alerts into Administer.

Key Changes

Categories Restructured

  • ❌ Deleted: "Logging alerts" category
  • ❌ Deleted: "Scheduling resources" category
  • ✅ Updated: Install category (added 3 Uninstall assemblies)
  • ✅ Repurposed: Administer category (new content: Scheduling + Alerts)

Assemblies Moved (7 total)

Uninstall (3): administering/ → installing/

  • uninstall-the-logging-operator.adoc
  • uninstall-the-loki-operator.adoc
  • uninstall-the-uiplugin.adoc

Alerts (3): logging_alerts/ → administering/

  • default-logging-alerts.adoc → understand-default-logging-alerts.adoc
  • custom-logging-alerts.adoc → configure-custom-logging-alerts.adoc
  • configuring-loki-log-based-alerts.adoc → configure-log-based-alerts.adoc

Scheduling (1): scheduling_resources/ → administering/

  • scheduling-logging-resources.adoc → schedule-logging-resources.adoc

Assembly Renaming

All renamed assemblies updated with:

  • Imperative tone titles
  • Anchor IDs matching new filenames
  • Context variables matching new filenames

Cross-References Updated

  • troubleshooting/troubleshoot-logging-alerts.adoc (2 xrefs)
  • administering/configure-log-based-alerts.adoc (2 xrefs)

Rationale

Based on the official "Product documentation categories" document:

Install Includes Uninstall

"Installation procedures, cluster creation, prerequisites verification, installer workflows, post-install checks, and uninstalling procedures."

Install is the full lifecycle category for getting the product in/out of your environment.

Administer is Day-2 Operations

"Operate and manage the product on an ongoing basis. Keep the product healthy, secure, and performing well in production."

  • Scheduling resources = Day-2 operational management (controlling where pods run)
  • Alerts = Managing logging platform health (not observing applications)

Why Not "Observe"?

The Observe category is for using logging to observe applications. Alerts for OpenShift Logging are about managing the logging platform itself, which is administration.

Final Structure

Install (10 assemblies)

  1. Installation overview
  2. Verify cluster prerequisites
  3. Configure object storage for LokiStack
  4. Install the Loki Operator
  5. Install the Red Hat OpenShift Logging Operator
  6. Install the Cluster Observability Operator
  7. Create the LokiStack
  8. Uninstall the Red Hat OpenShift Logging Operator ← NEW
  9. Uninstall the Loki Operator ← NEW
  10. Uninstall the UIPlugin ← NEW

Administer (4 assemblies)

  1. Schedule logging resources ← MOVED from Scheduling resources
  2. Understand default logging alerts ← MOVED from Logging alerts
  3. Configure custom logging alerts ← MOVED from Logging alerts
  4. Configure log-based alerts ← MOVED from Logging alerts

Troubleshoot (no changes)

  • Troubleshoot logging alerts (already here - reactive problem-solving)

Validation

  • ✅ Prow smoke test passed
  • ✅ All xrefs resolve correctly
  • ✅ Git history preserved with git mv
  • ✅ Imperative tone compliance
  • ✅ Anchor IDs match filenames

Files Changed

  • 9 files modified
  • 7 assemblies moved
  • 4 assemblies renamed
  • 2 categories dissolved
  • Topic map updated

Signed-off-by: John Wilkins jowilkin@redhat.com

🤖 Generated with Claude Code

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

@openshift-ci openshift-ci Bot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Aug 6, 2026
@ocpdocs-previewbot

ocpdocs-previewbot commented Aug 6, 2026

Copy link
Copy Markdown

🤖 Thu Aug 06 02:11:04 - Prow CI generated the docs preview:

https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/administering/configure-custom-logging-alerts.html
https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/administering/configure-log-based-alerts.html
https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/administering/schedule-logging-resources.html
https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/administering/understand-default-logging-alerts.html
https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/installing/uninstall-the-logging-operator.html
https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/installing/uninstall-the-loki-operator.html
https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/installing/uninstall-the-uiplugin.html
https://117401--ocpdocs-pr.netlify.app/openshift-logging/latest/troubleshooting/troubleshoot-logging-alerts.html

@openshift-ci

openshift-ci Bot commented Aug 6, 2026

Copy link
Copy Markdown

@johnwilkins: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

jira/valid-reference Indicates that this PR references a valid Jira ticket of any type. size/M Denotes a PR that changes 30-99 lines, ignoring generated files.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@johnwilkins @openshift-ci-robot @ocpdocs-previewbot