Add JTBD analysis for OpenShift GitOps documentation#109918
Add JTBD analysis for OpenShift GitOps documentation#109918Dhruv-Soni11 wants to merge 2 commits intoopenshift:mainfrom
Conversation
…s 1.20 - Complete 4-step workflow analysis for managing_cluster_configuration (29 JTBD records: 4 main jobs, 6 user stories, 19 tasks) - Simplified job statements for managing_cluster_configuration - JTBD analysis for gitops-release-notes-1-20 (3 main jobs, 25 user stories covering new features, fixes, and errata) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit adds comprehensive Jobs-to-be-Done analysis files for multiple OpenShift GitOps documentation topics including installation, application management, ArgoCD agent architecture, application sets, multitenancy, and cluster configuration. Also includes the Claude memory system for context retention. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
openshift-ci
bot
added
the
size/XXL
|
🤖 Fri Apr 10 09:41:58 - Prow CI generated the docs preview: |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ShortDescription: Assign [role="_abstract"] to a paragraph to use it as in DITA.
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ContentType: The '_mod-docs-content-type' attribute definition is missing.
There was a problem hiding this comment.
🤖 [error] OpenShiftAsciiDoc.ModuleContainsContentType: Module is missing the '_mod-docs-content-type' variable.
| Regardless of the mode, the control plane Argo CD instance always displays up-to-date application status across all clusters. The operational mode determines only where the authoritative specification resides, the direction of synchronization, and the ability to interact with that specification from the control plane. | ||
| ==== | ||
|
|
||
| === Argo CD Agent Managed mode |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.NestedSection: Level 2, 3, 4, and 5 sections are not supported in DITA.
| * Exposes workload clusters to risk if the control plane cluster is compromised, because it changes sync downstream. | ||
| * Creates a single point of failure in the control plane, preventing synchronization of application changes to workload clusters if the control plane is non-functional. | ||
|
|
||
| === Argo CD Agent Autonomous mode |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.NestedSection: Level 2, 3, 4, and 5 sections are not supported in DITA.
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ContentType: The '_mod-docs-content-type' attribute definition is missing.
There was a problem hiding this comment.
🤖 [error] OpenShiftAsciiDoc.ModuleContainsContentType: Module is missing the '_mod-docs-content-type' variable.
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ShortDescription: Assign [role="_abstract"] to a paragraph to use it as in DITA.
| // The {product-title} attribute provides the context-sensitive name of the relevant OpenShift distribution, for example, "OpenShift Container Platform" or "OKD". The {product-version} attribute provides the product version relative to the distribution, for example "4.9". | ||
| // {product-title} and {product-version} are parsed when AsciiBinder queries the _distro_map.yml file in relation to the base branch of a pull request. | ||
| // See https://github.com/openshift/openshift-docs/blob/main/contributing_to_docs/doc_guidelines.adoc#product-name-and-version for more information on this topic. | ||
| // Other common attributes are defined in the following lines: |
There was a problem hiding this comment.
🤖 [error] OpenShiftAsciiDoc.SuggestAttribute: Use the AsciiDoc attribute '{gitops-title}' rather than the plain text product term 'Red Hat OpenShift GitOps', unless your use case is an exception.
|
|
||
| :cluster-manager-first: Red Hat OpenShift Cluster Manager | ||
| :cluster-manager: OpenShift Cluster Manager | ||
| :cluster-manager-url: link:https://console.redhat.com/openshift[OpenShift Cluster Manager Hybrid Cloud Console] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| :cluster-manager-first: Red Hat OpenShift Cluster Manager | ||
| :cluster-manager: OpenShift Cluster Manager | ||
| :cluster-manager-url: link:https://console.redhat.com/openshift[OpenShift Cluster Manager Hybrid Cloud Console] | ||
| :cluster-manager-url-pull: link:https://console.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| = Managing the application set resources in non-control plane namespaces | ||
| :context: managing-app-sets-in-non-control-plane-namespaces | ||
|
|
||
| toc::[] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
|
|
||
| toc::[] | ||
|
|
||
| [role="_abstract"] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| // When including this file, ensure that {FeatureName} is set immediately before | ||
| // the include. Otherwise it will result in an incorrect replacement. | ||
|
|
||
| [IMPORTANT] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| // the include. Otherwise it will result in an incorrect replacement. | ||
|
|
||
| [IMPORTANT] | ||
| ==== |
There was a problem hiding this comment.
🤖 [error] AsciiDoc.ValidAdmonitionBlocks: Unterminated admonition block found in file.
| // the include. Otherwise it will result in an incorrect replacement. | ||
|
|
||
| [IMPORTANT] | ||
| ==== |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.TaskExample: Examples are allowed only once in DITA tasks.
| // the include. Otherwise it will result in an incorrect replacement. | ||
|
|
||
| [IMPORTANT] | ||
| ==== |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ExampleBlock: Examples can not be inside of other blocks in DITA.
| // the include. Otherwise it will result in an incorrect replacement. | ||
|
|
||
| [IMPORTANT] | ||
| ==== |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
|
|
||
| [IMPORTANT] | ||
| ==== | ||
| [subs="attributes+"] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| [IMPORTANT] | ||
| ==== | ||
| [subs="attributes+"] | ||
| {FeatureName} is a Technology Preview feature only. Technology Preview features |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| ==== | ||
| [subs="attributes+"] | ||
| {FeatureName} is a Technology Preview feature only. Technology Preview features | ||
| are not supported with Red Hat production service level agreements (SLAs) and |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| [subs="attributes+"] | ||
| {FeatureName} is a Technology Preview feature only. Technology Preview features | ||
| are not supported with Red Hat production service level agreements (SLAs) and | ||
| might not be functionally complete. Red Hat does not recommend using them |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| {FeatureName} is a Technology Preview feature only. Technology Preview features | ||
| are not supported with Red Hat production service level agreements (SLAs) and | ||
| might not be functionally complete. Red Hat does not recommend using them | ||
| in production. These features provide early access to upcoming product |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| are not supported with Red Hat production service level agreements (SLAs) and | ||
| might not be functionally complete. Red Hat does not recommend using them | ||
| in production. These features provide early access to upcoming product | ||
| features, enabling customers to test functionality and provide feedback during |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| might not be functionally complete. Red Hat does not recommend using them | ||
| in production. These features provide early access to upcoming product | ||
| features, enabling customers to test functionality and provide feedback during | ||
| the development process. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| features, enabling customers to test functionality and provide feedback during | ||
| the development process. | ||
|
|
||
| For more information about the support scope of Red Hat Technology Preview features, see link:https://access.redhat.com/support/offerings/techpreview/[Technology Preview Features Support Scope]. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| [role="_abstract"] | ||
| The `argocd.argoproj.io/managed-by-url` annotation allows an Application resource to specify which Argo CD instance manages it. This annotation ensures application links in the user interface point to the correct managing instance. | ||
|
|
||
| When you use multiple Argo CD instances with the app-of-apps pattern: |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
|
|
||
| When you use multiple Argo CD instances with the app-of-apps pattern: | ||
|
|
||
| * A primary Argo CD instance creates a parent Application. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| When you use multiple Argo CD instances with the app-of-apps pattern: | ||
|
|
||
| * A primary Argo CD instance creates a parent Application. | ||
| * The parent Application deploys child Applications that a secondary Argo CD instance manages. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
|
|
||
| * A primary Argo CD instance creates a parent Application. | ||
| * The parent Application deploys child Applications that a secondary Argo CD instance manages. | ||
| * Without the annotation, clicking on child Applications in the primary instance's user interface attempts to open them in the primary instance, which is incorrect. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| * A primary Argo CD instance creates a parent Application. | ||
| * The parent Application deploys child Applications that a secondary Argo CD instance manages. | ||
| * Without the annotation, clicking on child Applications in the primary instance's user interface attempts to open them in the primary instance, which is incorrect. | ||
| * With the annotation, child Applications correctly open in the secondary instance. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| * Without the annotation, clicking on child Applications in the primary instance's user interface attempts to open them in the primary instance, which is incorrect. | ||
| * With the annotation, child Applications correctly open in the secondary instance. | ||
|
|
||
| The `managed-by-url` annotation ensures application links redirect to the correct Argo CD instance. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
|
|
||
| [NOTE] | ||
| ==== | ||
| This annotation is particularly useful in multitenant setups where different teams have their own Argo CD instances, or in hub-and-spoke architectures where a central instance manages multiple edge instances. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
|
|
||
| :_mod-docs-content-type: PROCEDURE | ||
| [id="gitops-configuring-managed-by-url-annotation_{context}"] | ||
| = Configuring the managed-by-url annotation |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| = Configuring the managed-by-url annotation | ||
|
|
||
| [role="_abstract"] | ||
| You can configure the `argocd.argoproj.io/managed-by-url` annotation to direct application links to the correct Argo CD instance in multi-instance environments. |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.RelatedLinks: Content other than links cannot be mapped to DITA related-links.
| spec: | ||
| project: default | ||
| source: | ||
| repoURL: https://github.com/YOUR-ORG/my-apps-repo.git |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| name: child-app | ||
| namespace: namespace-b | ||
| annotations: | ||
| argocd.argoproj.io/managed-by-url: "https://secondary-argocd.example.com" |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| spec: | ||
| project: default | ||
| source: | ||
| repoURL: https://github.com/YOUR-ORG/my-apps-repo.git |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
|
|
||
| * `https://argocd.example.com` | ||
| * `https://argocd.example.com:8080` | ||
| * `http://localhost:8080` |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| // IBM Power | ||
| :ibmpowerProductName: IBM Power | ||
| // IBM zSystems | ||
| :ibmzProductName: IBM zSystems |
There was a problem hiding this comment.
🤖 [error] OpenShiftAsciiDoc.SuggestAttribute: Use the AsciiDoc attribute '{product-title}' rather than the plain text product term 'OpenShift Container Platform', unless your use case is an exception.
|
|
||
| :cluster-manager-first: Red Hat OpenShift Cluster Manager | ||
| :cluster-manager: OpenShift Cluster Manager | ||
| :cluster-manager-url: link:https://console.redhat.com/openshift[OpenShift Cluster Manager Hybrid Cloud Console] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| :cluster-manager-first: Red Hat OpenShift Cluster Manager | ||
| :cluster-manager: OpenShift Cluster Manager | ||
| :cluster-manager-url: link:https://console.redhat.com/openshift[OpenShift Cluster Manager Hybrid Cloud Console] | ||
| :cluster-manager-url-pull: link:https://console.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| This sample workflow walks you through the process of configuring Argo CD to recursively sync the content of the `cluster` directory to the `cluster-configs` application. The directory defines the {OCP} cluster configurations and the `spring-petclinic` namespace on the cluster. | ||
| endif::cluster[] | ||
|
|
||
| .Prerequisites |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.TaskDuplicate: Duplicate titles cannot be mapped to DITA tasks.
| * You have installed the {gitops-title} `argocd` CLI. | ||
| * You have logged in to Argo CD instance. | ||
|
|
||
| .Procedure |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.TaskDuplicate: Duplicate titles cannot be mapped to DITA tasks.
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ ADMIN_PASSWD=$(oc get secret openshift-gitops-cluster -n openshift-gitops -o jsonpath='{.data.admin\.password}' | base64 -d) |
There was a problem hiding this comment.
🤖 [error] OpenShiftAsciiDoc.TrailingBackslash: Code example ends with an unescaped trailing backslash.
| + | ||
| [source,terminal] | ||
| ---- | ||
| $ argocd app create app-spring-petclinic \ |
There was a problem hiding this comment.
🤖 [error] OpenShiftAsciiDoc.TrailingBackslash: Code example ends with an unescaped trailing backslash.
| [source,terminal] | ||
| ---- | ||
| $ argocd app create app-spring-petclinic \ | ||
| --repo https://github.com/redhat-developer/openshift-gitops-getting-started.git \ |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| --repo https://github.com/redhat-developer/openshift-gitops-getting-started.git \ | ||
| --path app \ | ||
| --revision main \ | ||
| --dest-server https://kubernetes.default.svc \ |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| [source,terminal] | ||
| ---- | ||
| $ argocd app create app-spring-petclinic --core \ | ||
| --repo https://github.com/redhat-developer/openshift-gitops-getting-started.git \ |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| --repo https://github.com/redhat-developer/openshift-gitops-getting-started.git \ | ||
| --path app \ | ||
| --revision main \ | ||
| --dest-server https://kubernetes.default.svc \ |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
|
|
||
| [role="_additional-resources"] | ||
| [id="additional-resources_{context}"] | ||
| == Additional resources |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.TaskSection: Sections are not allowed in DITA tasks.
| // IBM Power | ||
| :ibmpowerProductName: IBM Power | ||
| // IBM zSystems | ||
| :ibmzProductName: IBM zSystems |
There was a problem hiding this comment.
🤖 [error] OpenShiftAsciiDoc.SuggestAttribute: Use the AsciiDoc attribute '{product-title}' rather than the plain text product term 'OpenShift Container Platform', unless your use case is an exception.
|
|
||
| :cluster-manager-first: Red Hat OpenShift Cluster Manager | ||
| :cluster-manager: OpenShift Cluster Manager | ||
| :cluster-manager-url: link:https://console.redhat.com/openshift[OpenShift Cluster Manager Hybrid Cloud Console] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| :cluster-manager-first: Red Hat OpenShift Cluster Manager | ||
| :cluster-manager: OpenShift Cluster Manager | ||
| :cluster-manager-url: link:https://console.redhat.com/openshift[OpenShift Cluster Manager Hybrid Cloud Console] | ||
| :cluster-manager-url-pull: link:https://console.redhat.com/openshift/install/pull-secret[pull secret from the Red Hat OpenShift Cluster Manager] |
There was a problem hiding this comment.
🤖 [error] AsciiDocDITA.ConceptLink: Move all links and cross references to Additional resources.
| // Module included in the following assemblies: | ||
| // | ||
| // * argocd_applications/deploying-a-spring-boot-application-with-argo-cd.adoc | ||
| endif::[] |
There was a problem hiding this comment.
🤖 [error] AsciiDoc.ValidConditions: File contains unbalanced if statements. Review the file to ensure it contains matching opening and closing if statements.
|
@Dhruv-Soni11: all tests passed! Full PR test history. Your PR dashboard. DetailsInstructions 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. |
3 participants
Summary
Test plan
🤖 Generated with Claude Code