docs: brief info about contributing ref pages (#2446)

Signed-off-by: Meg McRoberts <meg.mcroberts@dynatrace.com>
Signed-off-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>
Co-authored-by: Moritz Wiesinger <moritz.wiesinger@dynatrace.com>
Co-authored-by: Giovanni Liva <giovanni.liva@dynatrace.com>
Co-authored-by: odubajDT <93584209+odubajDT@users.noreply.github.com>

docs/content/en/contribute/docs/source-file-structure/_index.md

@@ -63,6 +63,60 @@ In the order they appear in the rendered docs, the subdirectories are:
   Information to help users who are migrating to Keptn
   from Keptn v1
 
+### Working with reference pages
+
+The Keptn documentation includes two reference sections
+that document the Keptn APIs and CRDs.
+For background information, see:
+
+* [Kubernetes API Concepts](https://kubernetes.io/docs/reference/using-api/api-concepts/)
+* [Kubernetes API Reference](https://kubernetes.io/docs/reference/kubernetes-api/)
+
+#### API Reference
+
+The
+[API Reference](https://lifecycle.keptn.sh/docs/crd-ref/)
+pages are autogenerated from the source code.
+This is a comprehensive list of all APIs and resources Keptn uses,
+most of which users seldom see.
+
+Descriptive text for the APIs is authored in the source code itself.
+Each operator has its own API library with different versions.
+The source locations are:
+
+* [Lifecycle API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/lifecycle)
+* [Metrics API](https://github.com/keptn/lifecycle-toolkit/tree/main/metrics-operator/api)
+* [Options API](https://github.com/keptn/lifecycle-toolkit/tree/main/lifecycle-operator/apis/options)
+
+The text is coded in a limited form of markdown.
+
+To regenerate the autogenerated API reference docs,
+execute the following script
+in the root directory of your `lifecycle-toolkit` clone:
+
+```shell
+./.github/scripts/generate-crd-docs/generate-crd-docs.sh
+```
+
+#### CRD Reference
+
+The
+[CRD Reference](https://lifecycle.keptn.sh/docs/yaml-crd-ref/)
+pages
+describe the YAML files used to populate resources
+for the small set of CRDs that users must populate themselves.
+These are currently authored manually
+and should provide as much information as possible about the resource.
+These are intended to be reference pages that are used regularly
+by users after they are familiar with how to use Keptn.
+For new users, the
+[User Guides](https://lifecycle.keptn.sh/docs/implementing/)
+provide introductory material about how to use various features.
+
+A template to use to create a new CRD Reference page
+is available
+[here](../templates/yaml-crd-ref-template.md).
+
 ## Contributing guide
 
 The source for the

docs/content/en/contribute/docs/templates/yaml-crd-ref-template.md

@@ -0,0 +1,66 @@
+---
+title: CRD name
+description: template for new CRD reference pages
+weight: 20
+---
+
+Copy this template to create a new CRD reference page.
+
+1. Replace the variable text in metadata with information for this page
+1. Delete these instructions from your file
+1. Populate the page with appropriate content
+
+## Synopsis
+
+```yaml
+apiVersion: <library>
+kind: <kind>
+metadata:
+  name: <name>
+spec:
+  ...
+```
+
+## Fields
+
+<!-- Detailed description of each field/parameter -->
+
+<!-- * **apiVersion** -- API version being used -->
+<!-- * **kind** -- Resource type. -->
+<!--    Must be set to `<xxx>` -->
+<!-- * **metadata** -->
+<!--   * **name** -- Unique name of this <resource>. -->
+<!--     Names must comply with the -->
+<!-- markdownlint-disable-next-line line-length -->
+<!--     [Kubernetes Object Names and IDs](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-subdomain-names) -->
+<!--     specification. -->
+<!-- * **spec** -->
+<!-- ... -->
+
+Fields should be clearly marked as to whether they are
+required or optional.
+If they are optional,
+text should explain the behavior when that field is not populated.
+
+## Usage
+
+<!-- How this CRD is "activated".  For example, which event uses this CRD -->
+<!-- Instructions and guidelines for when and how to customize a CRD -->
+
+## Examples
+
+Include code snippets that illustrate
+how this resource is populated.
+Code examples should use be embedded links to example source code
+so that they will be updated automatically when changes are made to the example.
+
+## Files
+
+* Link to subsection for this resource in the "API Reference"
+
+## Differences between versions
+
+## See also
+
+* Links to related reference pages
+* Links to related User Guides and other documentation