docs: combine API and CRD reference index pages into one (#2849)

Signed-off-by: Geoffrey Israel <israelgeoffrey13@gmail.com>
Co-authored-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>

docs/docs/reference/api-reference/index.md

@@ -4,44 +4,5 @@ comments: true
 
 # API Reference
 
-This section provides comprehensive reference information about all APIs
-that are defined In Keptn.
-This section is auto-generated from source code.
-
-Each CRD is an object of an API library.
-Keptn APIs follow the Kubernetes API versioning scheme.
-and are themselves composed of objects and sub-objects.
-The Keptn CRDs extend the base Kubernetes API
-with new objects and functionality.
-Keptn APIs follow API versioning conventions recommended by Kubernetes.
-
-Keptn generates most of the resources it needs
-without requiring manual input.
-[Lifecycle CRD Reference and Metrics CRD Reference](../crd-reference/index.md)
-contains reference pages for the manifests
-that must be populated manually.
-
-Use `kubectl` to inspect the current contents of any Keptn resource:
-
-1. List all resources of the specified type within a certain namespace.
-   For example, to list all the `KeptnApp` resources
-   in the `namespace1` namespace, the command is:
-
-        kubectl get keptnapps -n namespace1
-
-2. Get the current manifest for the specified resource.
-   For example, to view the manifest for the `my-keptn-app` resource
-   in the `namespace1` namespace, the command is:
-
-        kubectl get keptnapp -n <namespace> my-keptn-app -oyaml
-
-For more information about the APIs and Custom Resources,
-see the Kubernetes documentation:
-
-* [API Overview](https://kubernetes.io/docs/reference/using-api/)
-
-* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
-
-* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
-
-* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)
+Delve into comprehensive reference information about all APIs defined in Keptn.
+This auto-generated content offers insights into the structure, versioning, and functionality of Keptn APIs.

docs/docs/reference/crd-reference/index.md

@@ -4,22 +4,5 @@ comments: true
 
 # CRD Reference
 
-This section provides comprehensive reference information about the
-manifest files that must be populated for Keptn
-[Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/).
-
-Each CRD is an object of an API library.
-In addition to the CRDs documented in this section,
-Keptn populates many resources on its own.
-For a comprehensive list of all Keptn resources, see
-[API Reference](../api-reference/index.md).
-
-For more information about CRDs and APIs, see the Kubernetes documentation:
-
-* [API Overview](https://kubernetes.io/docs/reference/using-api/)
-
-* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
-
-* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
-
-* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)
+Explore the manifest files crucial for customizing Keptn Custom Resource Definitions (CRDs)
+that you need to define the behavior of Keptn.

docs/docs/reference/index.md

@@ -4,12 +4,35 @@ comments: true
 
 # Reference
 
-This section of the Keptn documentation contains reference documentation for the various APIs and CRDs that are used in Keptn.
+Welcome to the Keptn documentation reference section,
+which provides comprehensive information about the Keptn Custom Resource Definitions (CRDs) and APIs used in Keptn.
 
-If you want to learn more about specific Custom Resource Definitions
-that you may need to populate to use Keptn,
-go to the
-[CRD Reference](./crd-reference/index.md) section.
+## CRD Reference
 
-If you want to look up some specific object properties or want ot know more about the internal APIs of Keptn,
-Go to the [API Reference](./api-reference/index.md) section.
+While the [API Reference](./api-reference/index.md) caters to advanced users with detailed technical specifications,
+the CRD Reference serves as a more user-friendly alternative.
+It presents the same information found in the API Reference but in a format
+that is particularly useful for individuals who are not extremely advanced users.
+While many resources are automatically populated,
+the CRD Reference guides you through the manual steps for specific manifests.
+
+For a comprehensive list of all Keptn resources, see the [API Reference](./api-reference/index.md).
+
+## API Reference
+
+The [API Reference](./api-reference/index.md) is content that is auto-generated from source code
+and offers insights into the structure,
+versioning, and functionality of Keptn APIs.
+
+Each API corresponds to an object in our API library, following Kubernetes API versioning.
+Keptn APIs extend the base Kubernetes API with additional objects and functionality.
+Notably, Keptn generates many of its resources automatically, minimizing the need for manual input.
+
+## Learn more
+
+To learn more about CRDs, APIs, and Kubernetes objects, consult the Kubernetes documentation:
+
+* [API Overview](https://kubernetes.io/docs/reference/using-api/)
+* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning)
+* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/)