From bc1ead54a0c262415ab41c21b92501e368756ab8 Mon Sep 17 00:00:00 2001
From: Meg McRoberts <meg.mcroberts@dynatrace.com>
Date: Thu, 21 Mar 2024 05:09:49 -0700
Subject: [PATCH] docs: fix info about %include for sample files (#3246)

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>
---
 docs/docs/contribute/docs/code-docs.md        | 29 ++++++++++++++++++-
 .../docs/contrib-guidelines-docs.md           | 12 ++------
 2 files changed, 31 insertions(+), 10 deletions(-)

diff --git a/docs/docs/contribute/docs/code-docs.md b/docs/docs/contribute/docs/code-docs.md
index d17e0251e4..1e26462caf 100644
--- a/docs/docs/contribute/docs/code-docs.md
+++ b/docs/docs/contribute/docs/code-docs.md
@@ -19,7 +19,7 @@ The following documents document the language:
 Markdown supports many variants and the build tools we use
 impose a few special requirements that are discussed here.
 
-## Frontmatter requirements
+## Front matter requirements
 
 The top of each documentation source file should look like:
 
@@ -65,6 +65,33 @@ as in:
 <!-- This is a comment -->
 ```
 
+## Displaying sample files
+
+Most Keptn configuration is implemented as YAML files
+that define a resource
+so displaying an example file is very useful.
+However, the file content should not be put directly into your doc source.
+Instead, the sample file is put into an `assets` directory
+and then "included" in your file.
+This keeps the documentation source cleaner
+and enables us to run tests to ensure that the YAML file is valid
+as Keptn evolves.
+
+To implement this:
+
+1. Either identify the file you want to include
+   in the `assets` directory next to your documentation file
+   or create your sample YAML file in that tree,
+   giving it an appropriate name, including the `.yaml` suffix.
+
+2. Use the `include <file-path>` shortcode
+   to include this file in your documentation source inside a code block.
+   For example:
+
+      ```md
+      {% /* include "../../assets/crd/python-libs.yaml" %}
+      ```
+
 ## Indentation of nested lists and code blocks
 
 Paragraphs and code blocks that are nested under a list item
diff --git a/docs/docs/contribute/docs/contrib-guidelines-docs.md b/docs/docs/contribute/docs/contrib-guidelines-docs.md
index 723c8c63b3..9ea76b9f4a 100644
--- a/docs/docs/contribute/docs/contrib-guidelines-docs.md
+++ b/docs/docs/contribute/docs/contrib-guidelines-docs.md
@@ -50,15 +50,9 @@ that are relevant only to documentation.
   use the `include <file-path>` shortcode syntax
   (which automatically pulls the current version of the file into your document)
   rather than copying the text.
-  This ensures that, when the sample file is updated,
-  your document is also updated.
-
-    For example, to include the `examples/sample-app/version1/app-pre-deploy-eval.yaml` file,
-    the syntax is:
-
-    ```md
-    {% /* include "examples/sample-app/version-1/app-pre-deploy-eval.yaml" */ %}
-    ```
+  See
+  [Displaying sample files](code-docs.md/#comments)
+  for details.
 
 * `markdownlint` enforces limits on line length.
   Links to other documents are exempted from this limit