Uploaded image for project: 'OpenShift Top Level Product Strategy'
  1. OpenShift Top Level Product Strategy
  2. OCPPLAN-7769

[Improved upstream docs] With "high-level intro", "scaffolding overview", and "how to- in steps" for features

XMLWordPrintable

    • Icon: Feature Feature
    • Resolution: Done
    • Icon: Normal Normal
    • 2021Q2 Plan
    • None
    • None
    • None
    • 0% To Do, 0% In Progress, 100% Done

      Goal:
      Provides more guidance in steps for how to adopt features provided by SDK (or underlying libraries that has dependencies) in users' Operator projects.

      Benefit:
      With that, the community can easier refer, share, discuss, and learn by following the examples to grow, elevate, and mature the capabilities of the Operators.

      Why is this important:
      From the upstream SDK repo and survey, Operator authors often reached out to SDK doc for learning features and seeking guidance on how to adopt those in their Operator project.

      Currently, SDK doc does provide great coverage in terms of the features/capabilities provided by SDK itself or the underlying/dependency libraries (e.g. kubebuilder, controller-runtime, or controller-gen). However, in many cases, the doc only links out to another upstream doc for that specific upstream libraries (e.g. kubebuilder or controller-runtime) with little context.

      Acceptance criteria:
      We don't think it makes sense to have a completely duplicated the documentation effort in the SDK doc site for other underlying libraries, but rather having a "meta doc" on:

      1. "an high level intro/overview of this feature"
      2. "what benefits this feature gives you"
      3. "what files will get scaffolded (or need to be manually added)"
      4. "how to edit/change/set these files in steps + per use cases"

      to help set the scene, and then links out to other upstream external doc for "more details" (e.g. some specific kubebuilder-based or controller-runtime-based tasks), would greatly help users to grasp the idea and enable themselves to learn.

            Unassigned Unassigned
            DanielMesser Daniel Messer
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: