diff --git a/.github/scripts/generate-crd-docs/generate-crd-docs.sh b/.github/scripts/generate-crd-docs/generate-crd-docs.sh
index cc2fb02f73..6effbb2217 100755
--- a/.github/scripts/generate-crd-docs/generate-crd-docs.sh
+++ b/.github/scripts/generate-crd-docs/generate-crd-docs.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# CRD docs auto generation script
+# API docs auto generation script
 #
 # This script goes through all API definitions in the operator/apis folder
 # and generates docs from code for each API group and version
@@ -23,11 +23,11 @@ else
   echo "Docs generator is installed, continuing..."
 fi
 
-echo "Running CRD docs auto-generator..."
+echo "Running API docs auto-generator..."
 
 for api_group in "$API_ROOT"*; do
   sanitized_api_group="${api_group#$API_ROOT}"
-  INDEX_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/_index.md"
+  INDEX_PATH="./docs/content/en/docs/api-ref/$sanitized_api_group/_index.md"
 
   if [ ! -f "$INDEX_PATH" ]; then
     echo "API group index file doesn't exist for group $sanitized_api_group. Creating it now..."
@@ -41,7 +41,7 @@ for api_group in "$API_ROOT"*; do
   for api_version in "$api_group"/*; do
     sanitized_api_version="${api_version#$API_ROOT$sanitized_api_group/}"
 
-    OUTPUT_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/$sanitized_api_version"
+    OUTPUT_PATH="./docs/content/en/docs/api-ref/$sanitized_api_group/$sanitized_api_version"
 
     echo "Arguments:"
     echo "TEMPLATE_DIR: $TEMPLATE_DIR"
@@ -55,7 +55,7 @@ for api_group in "$API_ROOT"*; do
     echo "Creating docs folder $OUTPUT_PATH..."
     mkdir -p "$OUTPUT_PATH"
 
-    echo "Generating CRD docs for $sanitized_api_group.$API_DOMAIN/$sanitized_api_version..."
+    echo "Generating API docs for $sanitized_api_group.$API_DOMAIN/$sanitized_api_version..."
     crd-ref-docs \
       --templates-dir "$TEMPLATE_DIR" \
       --source-path="./$api_version" \
diff --git a/.github/workflows/markdown-checks.yaml b/.github/workflows/markdown-checks.yaml
index 39a0b22eca..c536e8e457 100644
--- a/.github/workflows/markdown-checks.yaml
+++ b/.github/workflows/markdown-checks.yaml
@@ -77,18 +77,18 @@ jobs:
 
       - name: Copy old docs
         run: |
-          cp -R ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old
+          cp -R ./docs/content/en/docs/api-ref ./docs/content/en/docs/api-ref-old
 
       - name: Run docs generator
         run: ./.github/scripts/generate-crd-docs/generate-crd-docs.sh
 
       - name: Check if docs are up to date
         run: |
-          if ! diff -rq ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old &>/dev/null; then
+          if ! diff -rq ./docs/content/en/docs/api-ref ./docs/content/en/docs/api-ref-old &>/dev/null; then
             echo "The CRD docs have changes that are not reflected in the docs pages. Please use ./.github/scripts/generate-crd-docs/generate-crd-docs.sh to re-generate the docs."
             echo ""
             echo "=========== Diff ==========="
-            diff -ru ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old
+            diff -ru ./docs/content/en/docs/api-ref ./docs/content/en/docs/api-ref-old
             exit 1
           else
             echo ""
diff --git a/docs/.htmltest.yml b/docs/.htmltest.yml
index 9f9ba77c85..a40d1e61fe 100644
--- a/docs/.htmltest.yml
+++ b/docs/.htmltest.yml
@@ -2,7 +2,7 @@
 CheckDoctype: false
 IgnoreDirs:
   - favicons
-  - docs/crd-ref/lifecycle/
+  - docs/api-ref/lifecycle/
 IgnoreURLs:
   - "linkedin.com"
   - "localhost"
diff --git a/docs/content/en/docs/api-ref/_index.md b/docs/content/en/docs/api-ref/_index.md
new file mode 100644
index 0000000000..4bda1b6dd5
--- /dev/null
+++ b/docs/content/en/docs/api-ref/_index.md
@@ -0,0 +1,26 @@
+---
+title: API Reference
+description: Reference information about the KLT CRDs
+weight: 100
+hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
+---
+
+This section provides comprehensive reference information about the
+[Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
+that are defined for the Keptn Lifecycle Toolkit.
+
+> **Note**
+This section is under development.
+Information that is published here has been reviewed for technical accuracy
+but the format and content is still evolving.
+We welcome your input!**
+
+By introducing CRDs, Keptn is extending the base Kubernetes API with new objects and functionality.
+Keptn APIs follow API versioning conventions recommended by Kubernetes and are themselves composed of objects and sub-objects.
+
+For more information, 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/)
diff --git a/docs/content/en/docs/api-ref/lifecycle/_index.md b/docs/content/en/docs/api-ref/lifecycle/_index.md
new file mode 100644
index 0000000000..1086280488
--- /dev/null
+++ b/docs/content/en/docs/api-ref/lifecycle/_index.md
@@ -0,0 +1,4 @@
+---
+title: Lifecycle API
+description: Reference information about the Lifecycle API group
+---
diff --git a/docs/content/en/docs/crd-ref/lifecycle/v1alpha1/_index.md b/docs/content/en/docs/api-ref/lifecycle/v1alpha1/_index.md
similarity index 100%
rename from docs/content/en/docs/crd-ref/lifecycle/v1alpha1/_index.md
rename to docs/content/en/docs/api-ref/lifecycle/v1alpha1/_index.md
diff --git a/docs/content/en/docs/crd-ref/lifecycle/v1alpha2/_index.md b/docs/content/en/docs/api-ref/lifecycle/v1alpha2/_index.md
similarity index 100%
rename from docs/content/en/docs/crd-ref/lifecycle/v1alpha2/_index.md
rename to docs/content/en/docs/api-ref/lifecycle/v1alpha2/_index.md
diff --git a/docs/content/en/docs/crd-ref/lifecycle/v1alpha3/_index.md b/docs/content/en/docs/api-ref/lifecycle/v1alpha3/_index.md
similarity index 100%
rename from docs/content/en/docs/crd-ref/lifecycle/v1alpha3/_index.md
rename to docs/content/en/docs/api-ref/lifecycle/v1alpha3/_index.md
diff --git a/docs/content/en/docs/crd-ref/metrics/_index.md b/docs/content/en/docs/api-ref/metrics/_index.md
similarity index 100%
rename from docs/content/en/docs/crd-ref/metrics/_index.md
rename to docs/content/en/docs/api-ref/metrics/_index.md
diff --git a/docs/content/en/docs/crd-ref/metrics/v1alpha1/_index.md b/docs/content/en/docs/api-ref/metrics/v1alpha1/_index.md
similarity index 100%
rename from docs/content/en/docs/crd-ref/metrics/v1alpha1/_index.md
rename to docs/content/en/docs/api-ref/metrics/v1alpha1/_index.md
diff --git a/docs/content/en/docs/crd-ref/options/_index.md b/docs/content/en/docs/api-ref/options/_index.md
similarity index 100%
rename from docs/content/en/docs/crd-ref/options/_index.md
rename to docs/content/en/docs/api-ref/options/_index.md
diff --git a/docs/content/en/docs/crd-ref/options/v1alpha1/_index.md b/docs/content/en/docs/api-ref/options/v1alpha1/_index.md
similarity index 100%
rename from docs/content/en/docs/crd-ref/options/v1alpha1/_index.md
rename to docs/content/en/docs/api-ref/options/v1alpha1/_index.md
diff --git a/docs/content/en/docs/crd-ref/TaskDefinition/index.md b/docs/content/en/docs/crd-ref/TaskDefinition/index.md
new file mode 100644
index 0000000000..d3a350e7f6
--- /dev/null
+++ b/docs/content/en/docs/crd-ref/TaskDefinition/index.md
@@ -0,0 +1,288 @@
+---
+title: KeptnTaskDefinition
+description: Define tasks that can be run pre- or post-deployment
+weight: 89
+---
+
+A `KeptnTaskDefinition` defines tasks
+that are run by the Keptn Lifecycle Toolkit
+as part of the pre- and post-deployment phases of a `KeptnApp`.
+
+## Yaml Synopsis
+
+```yaml
+apiVersion: <lifecycle.keptn.sh/v?alpha?>
+kind: KeptnTaskDefinition
+metadata:
+  name: <task-name>
+spec:
+  function:
+    inline | httpRef | functionRef:
+    [parameters:
+      map:
+        textMessage: "This is my configuration"]
+    [secureParameters:
+      secret: slack-token]
+```
+
+## Fields
+
+* **apiVersion** -- API version being used.
+`
+* **kind** -- Resource type.  Must be set to `KeptnTaskDefinition`
+
+* **name** -- Unique name of this task.
+  * Must be an alphanumeric string and, by convention, is all lowercase.
+  * Can include the special characters `_`, `-`, <what others>.
+  * Should not include spaces.
+
+* **function** -- Code to be executed,
+  expressed as a [Deno](https://deno.land/) script.
+  Refer to [function runtime](https://github.com/keptn/lifecycle-toolkit/tree/main/functions-runtime)
+  for more information about the runtime.
+
+  The `function` can be defined as one of the following:
+
+  * **inline** - Include the actual executable code to execute.
+    This can be written as a full-fledged Deno script
+    that is included in this file.
+    For example:
+
+    ```yaml
+    function:
+      inline:
+        code: |
+          console.log("Deployment Task has been executed");
+    ```
+
+  * **httpRef** - Specify a Deno script to be executed at runtime
+    from the remote webserver that is specified.
+    For example:
+
+    ```yaml
+    name: hello-keptn-http
+      spec:
+        function:
+          httpRef:
+            url: "https://www.example.com/yourscript.js"
+    ```
+
+  * **functionRef** -- Execute another `KeptnTaskDefinition` that has been defined.
+    Populate this field with the value of the `name` field
+    for the `KeptnTaskDefinition` to be called.
+    This is commonly used to call a general function
+    that is used in multiple places, possibly with different parameters.
+    An example is:
+
+     ```yaml
+     spec:
+       function:
+         functionRef:
+           name: slack-notification
+     ```
+
+    This can also be used to group a set of tasks
+    into a single `KeptnTaskDefinition`,
+    such as defining a `KeptnTaskDefinition` for testing.
+    In this case, it other, existing `KeptnTaskDefinition`s
+    for each type of test to be run,
+    specifying each by the value of the `name` field.
+
+* **parameters** - An optional field to supply input parameters to a function.
+  The Lifecycle Toolkit passes the values defined inside the `map` field
+  as a JSON object.
+  For example:
+
+   ```yaml
+   spec:
+     parameters:
+       map:
+         textMessage: "This is my configuration"
+
+   The JSON object can be read
+   through the `DATA` environment variable using `Deno.env.get("DATA");`.
+
+   Multi-level maps are not supported at this time.
+
+   Currently only one secret can be passed.
+   The secret must have a `key` called `SECURE_DATA`.
+   It can be accessed via the environment variable `Deno.env.get("SECURE_DATA")`.
+   See [Context](#context) for details.
+
+* **secureParameters** -- An optional field used to pass a Kubernetes secret.
+  The `secret` value is the Kubernetes secret name
+  that is mounted into the runtime and made available to functions
+  using the `SECURE_DATA` environment variable.
+  For example:
+
+  ```yaml
+  secureParameters:
+    secret: slack-token
+
+   See [Create secret text](#create-secret-text) for details.
+
+## Usage
+
+A Task is responsible for executing the TaskDefinition of a workload.
+The execution is done by spawning a Kubernetes Job to handle a single Task.
+In its state, it tracks the current status of this Kubernetes Job.
+
+### Context
+
+A context environment variable is available via `Deno.env.get("CONTEXT")`.
+It can be used like this:
+
+```javascript
+let context = Deno.env.get("CONTEXT");
+
+if (contextdata.objectType == "Application") {
+    let application_name = contextdata.appName;
+    let application_version = contextdata.appVersion;
+}
+
+if (contextdata.objectType == "Workload") {
+    let application_name = contextdata.appName;
+    let workload_name = contextdata.workloadName;
+    let workload_version = contextdata.workloadVersion;
+}
+```
+
+### Create secret text
+
+```yaml
+# kubectl create secret generic my-secret --from-literal=SECURE_DATA=foo
+
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: dummy-task
+  namespace: "default"
+spec:
+  function:
+    secureParameters:
+      secret: my-secret
+    inline:
+      code: |
+        let secret_text = Deno.env.get("SECURE_DATA");
+        // secret_text = "foo"
+```
+
+This methodology supports multiple variables
+by creating a Kubernetes secret with a JSON string:
+
+```yaml
+# kubectl create secret generic my-secret \
+# --from-literal=SECURE_DATA="{\"foo\": \"bar\", \"foo2\": \"bar2\"}"
+
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: dummy-task
+  namespace: "default"
+spec:
+  function:
+    secureParameters:
+      secret: my-secret
+    inline:
+      code: |
+        let secret_text = Deno.env.get("SECURE_DATA");
+        let secret_text_obj = JSON.parse(secret_text);
+        // secret_text_obj["foo"] = "bar"
+        // secret_text_obj["foo2"] = "bar2"
+```
+
+## Examples
+
+**Example 1** defines a full-fledged Deno script
+within the `KeptnTaskDefinition` YAML file:
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: hello-keptn-inline
+spec:
+  function:
+    inline:
+      code: |
+        let text = Deno.env.get("DATA");
+        let data;
+        let name;
+        data = JSON.parse(text);
+
+        name = data.name
+        console.log("Hello, " + name + " new");
+```
+
+**Example 2** fetches the Deno script from a remote webserver at runtime:
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: hello-keptn-http
+spec:
+  function:
+    httpRef:
+      url: <url>
+```
+
+See the
+[sample-app/version-1](https://github.com/keptn-sandbox/lifecycle-toolkit-examples/blob/main/sample-app/version-1/app-pre-deploy.yaml)
+PodtatoHead example for a more complete example.
+
+**Example 3** calls another defined task,
+illustrating how one `KeptnTaskDefinition` can build
+on top of other `KeptnTaskDefinition`s.
+In this case, it calls `slack-notification-dev`,
+passing `parameters` and `secureParameters` to that other task:
+
+```yaml
+apiVersion: lifecycle.keptn.sh/v1alpha3
+kind: KeptnTaskDefinition
+metadata:
+  name: slack-notification-dev
+spec:
+  function:
+    functionRef:
+      name: slack-notification
+    parameters:
+      map:
+        textMessage: "This is my configuration"
+    secureParameters:
+      secret: slack-token
+```
+
+**More examples**
+
+* See the [operator/config/samples](https://github.com/keptn/lifecycle-toolkit/tree/main/operator/config/samples)
+directory for more example `KeptnTaskDefinition` YAML files.
+Separate examples are provided for each API version.
+For example, the `lifecycle_v1alpha3_keptntaskdefinition` file
+contains examples for the `v1alpha3` version of the lifecycle API group.
+
+>>>>>>> 0333070 (library -> API
)
+=======
+>>>>>>> 5b91097b2033a9e3c9fceefbbcca62544f9ab209
+## Files
+
+API Reference:
+
+* [KeptnTaskDefinition](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinition)
+* [KeptnTaskDefinitionList](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinitionlist)
+* [KeptnTaskDefinitionSpec](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinitionspec)
+* [FunctionReference](../../api-ref/lifecycle/v1alpha3/#functionreference)
+* [FunctionSpec](../../api-ref/lifecycle/v1alpha3/#functionspec)
+* [FunctionStatus](../../api-ref/lifecycle/v1alpha3/#functionstatus)
+* [HttpReference](../../api-ref/lifecycle/v1alpha3/#httpreference)
+* [Inline](../../api-ref/lifecycle/v1alpha3/#inline)
+
+## Differences between versions
+
+The `KeptnTaskDefinition` is the same for
+all `v1alpha?` library versions.
+
+## See also
+
+* Link to "use-case" guide pages that do something interesting with this CRD
+* Link to reference pages for any related CRDs
diff --git a/docs/content/en/docs/crd-ref/_index.md b/docs/content/en/docs/crd-ref/_index.md
index b96035fe53..d28ac526ab 100644
--- a/docs/content/en/docs/crd-ref/_index.md
+++ b/docs/content/en/docs/crd-ref/_index.md
@@ -1,7 +1,7 @@
 ---
-title: API Reference
+title: CRD Reference
 description: Reference information about the KLT CRDs
-weight: 100
+weight: 200
 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html
 ---
 
@@ -15,10 +15,10 @@ Information that is published here has been reviewed for technical accuracy
 but the format and content is still evolving.
 We welcome your input!**
 
-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.
+Each CRD is an object of an
+[API group](../../docs/api-ref/).
 By introducing CRDs, Keptn is extending the base Kubernetes API with new objects and functionality.
+Keptn APIs follow API versioning conventions recommended by Kubernetes and are themselves composed of objects and sub-objects.
 Keptn APIs follow API versioning conventions recommended by Kubernetes.
 
 For more information, see the Kubernetes documentation:
diff --git a/docs/content/en/docs/crd-ref/crd-template b/docs/content/en/docs/crd-ref/crd-template
new file mode 100644
index 0000000000..cc2f96dbfa
--- /dev/null
+++ b/docs/content/en/docs/crd-ref/crd-template
@@ -0,0 +1,35 @@
+---
+title: <crd-template>
+description: <one-line description of CRD>
+weight: <assign weight to create alphabetical order>
+hidden: true
+---
+
+Copy this template to create a new CRD reference page.
+
+1. Replace the variable text in metadata with information for this page
+1. Delete the `hidden: true` line
+1. Delete these instructions from your file
+1. Populate the page with appropriate content
+
+## Synopsis
+
+## Fields
+
+<!-- Detailed description of each field-->
+
+## 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
+
+**Example 1**
+
+## Files
+
+## Differences between versions
+
+## See also
+
diff --git a/docs/content/en/docs/crd-ref/lifecycle/_index.md b/docs/content/en/docs/crd-ref/lifecycle/_index.md
deleted file mode 100644
index c0fcb3d795..0000000000
--- a/docs/content/en/docs/crd-ref/lifecycle/_index.md
+++ /dev/null
@@ -1,4 +0,0 @@
----
-title: Lifecycle API
-description: Reference information about the Lifecycle API
----
diff --git a/docs/content/en/docs/tasks/write-tasks/_index.md b/docs/content/en/docs/tasks/write-tasks/_index.md
deleted file mode 100644
index 5480c12ce1..0000000000
--- a/docs/content/en/docs/tasks/write-tasks/_index.md
+++ /dev/null
@@ -1,113 +0,0 @@
----
-title: Write Keptn Tasks
-description: Learn how to use the Keptn Lifecycle Toolkit and explore basic features.
-icon: concepts
-layout: quickstart
-weight: 20
-hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html
----
-
-## Keptn Task Definition
-
-A `KeptnTaskDefinition` is a CRD used to define tasks that can be run by the Keptn Lifecycle Toolkit
-as part of pre- and post-deployment phases of a deployment. The task definition is a [Deno](https://deno.land/) script.
-In the future, we also intend to support other runtimes, especially running a container image directly.
-
-A task definition can be configured in three different ways:
-
-- inline
-- referring to an HTTP script
-- referring to another `KeptnTaskDefinition`
-
-An inline task definition looks like the following:
-
-```yaml
-apiVersion: lifecycle.keptn.sh/v1alpha2
-kind: KeptnTaskDefinition
-metadata:
-  name: deployment-hello
-spec:
-  function:
-    inline:
-      code: |
-        console.log("Deployment Task has been executed");
-```
-
-In the code section, it is possible to define a full-fletched Deno script.
-
-The runtime can also fetch the script on the fly from a remote webserver. For this, the CRD should look like the
-following:
-
-```yaml
-apiVersion: lifecycle.keptn.sh/v1alpha2
-kind: KeptnTaskDefinition
-metadata:
-  name: hello-keptn-http
-spec:
-  function:
-    httpRef:
-      url: <url>
-```
-
-Finally, `KeptnTaskDefinition` can build on top of other `KeptnTaskDefinition`s.
-This is a common use case where a general function can be re-used in multiple places with different parameters.
-
-```yaml
-apiVersion: lifecycle.keptn.sh/v1alpha2
-kind: KeptnTaskDefinition
-metadata:
-  name: slack-notification-dev
-spec:
-  function:
-    functionRef:
-      name: slack-notification
-    parameters:
-      map:
-        textMessage: "This is my configuration"
-    secureParameters:
-      secret: slack-token
-```
-
-As you might have noticed, Task Definitions also have the possibility to use input parameters.
-The Lifecycle Toolkit passes the values defined inside the `map` field as a JSON object.
-At the moment, multi-level maps are not supported.
-The JSON object can be read through the environment variable `DATA` using `Deno.env.get("DATA");`.
-Kubernetes secrets can also be passed to the function using the `secureParameters` field.
-
-Here, the `secret` value is the name of the K8s secret containing a field with the key `SECURE_DATA`.  
-The value of that field will then be available to the functions runtime via an environment variable called `SECURE_DATA`.
-
-For example, if you have a task function that should make use of secret data, you must first ensure that the secret
-containing the `SECURE_DATA` key exists, as e.g.:
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: deno-demo-secret
-  namespace: default
-type: Opaque
-data:
-  SECURE_DATA: YmFyCg== # base64 encoded string, e.g. 'bar'
-```
-
-Then, you can make use of that secret as follows:
-
-```yaml
-apiVersion: lifecycle.keptn.sh/v1alpha3
-kind: KeptnTaskDefinition
-metadata:
-  name: deployment-hello
-  namespace: "default"
-spec:
-  function:
-    secureParameters:
-      secret: deno-demo-secret
-    inline:
-      code: |
-        console.log("Deployment Hello Task has been executed");
-
-        let foo = Deno.env.get('SECURE_DATA');
-        console.log(foo);
-        Deno.exit(0);
-```