update templates and add template for concepts

On-behalf-of: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>

Author: morrison-sap

content_templates/template-concept.md

@@ -12,7 +12,10 @@ Write 2–4 sentences answering: *What is this? What problem does it solve? Wher
 
 Avoid "how to configure" or step-by-step instructions here. This section builds the mental model.
 
-> **Example:** A resolver maps component name patterns to OCM repositories. When OCM encounters a component reference during recursive resolution, it consults the configured resolvers to locate the right repository — without requiring the caller to know where each component lives.
+> **Example:** A resolver maps component name patterns to OCM repositories.
+> When OCM encounters a component reference during recursive resolution,
+> it consults the configured resolvers to locate the right repository — without
+> requiring the caller to know where each component lives.
 
 ## Why does it exist?
 
@@ -81,20 +84,23 @@ If this concept has common misconceptions, address them here briefly.
 
 ## Next steps
 
-- [How-to: <name>]({{< relref "docs/how-to/<file>.md" >}})
+Add links to related guides where you DO or LEARN more about the topic.
+
+- [How-To: <name>]({{< relref "docs/how-to/<file>.md" >}})
+- [Tutorial: <name>]({{< relref "docs/tutorials/<file>.md" >}})
 
 ## Related documentation
 
+Add links to related concepts and references that explain the WHY and provide more details.
+
 - [Concept: <name>]({{< relref "docs/concepts/<file>.md" >}})
-- [Tutorial: <name>]({{< relref "docs/tutorials/<file>.md" >}})
 - [Reference: <command>]({{< relref "docs/reference/<file>.md" >}})
 
 ---
 
 ## ✓ Before publishing
 
-Make sure to comply with our [CONTRIBUTING guide](../CONTRIBUTING.md),
-check the [Concept Writing Checklist](../CONTRIBUTING.md#concept-checklist),
+Make sure to comply with our [CONTRIBUTING guide](../CONTRIBUTING.md)
 and ensure the following:
 
 - [ ] Title is a noun or noun phrase — not a verb or task (e.g., "Resolvers", not "How to use resolvers")
@@ -105,5 +111,4 @@ and ensure the following:
 - [ ] Subsections address distinct orthogonal aspects
 - [ ] "Relationship to other concepts" section with relref links
 - [ ] "When to use it" section helps readers self-identify relevance
-- [ ] No CLI commands that constitute a workflow (short illustrative snippets are OK)
 - [ ] Working `relref` links throughout

content_templates/template-how-to.md

@@ -23,10 +23,6 @@ Include a diagram only if it clarifies the process. Keep it simple (3–5 nodes
 ```mermaid
 flowchart LR
     A[Input] --> B[ocm command] --> C[Output]
-    
-    style A fill:#e1f5ff,color:#000
-    style B fill:#fff4e6,color:#000
-    style C fill:#e8f5e9,color:#000
 ```
 
 One sentence explaining what this diagram shows.
@@ -45,68 +41,67 @@ See [Diagram Color Guide]({{< relref "content_templates/template-tutorial.md#dia
 
 ## Steps
 
-1. **Do the first thing**
+### Do the first thing
 
-   Brief explanation (1–2 sentences max). Link to concepts for "why"—don't explain inline.
+Brief explanation (1–2 sentences max). Link to concepts for "why"—don't explain inline.
 
-   ```bash
-   ocm <command> <args>
-   ```
+```bash
+ocm <command> <args>
+```
 
-   {{< callout type="tip" >}}
-   **Handling variants:** If your how-to covers multiple approaches or platforms, use tabs to show alternatives:
+{{< callout type="tip" >}}
+**Handling variants:** If your how-to covers multiple approaches or platforms, use tabs to show alternatives:
+{{< /callout >}}
 
-   {{< tabs "signing-methods" >}}
-   {{< tab "RSA Key" >}}
-   ```bash
-   ocm sign cv --private-key private.key
-   ```
-   {{< /tab >}}
-   {{< tab "Sigstore" >}}
-   ```bash
-   ocm sign cv --sigstore
-   ```
-   {{< /tab >}}
-   {{< /tabs >}}
-   {{< /callout >}}
+{{< tabs "signing-methods" >}}
+{{< tab "RSA Key" >}}
+```bash
+ocm sign cv --private-key private.key
+```
+{{< /tab >}}
+{{< tab "Sigstore" >}}
+```bash
+ocm sign cv --sigstore
+```
+{{< /tab >}}
+{{< /tabs >}}
 
-   You should see: `[specific success indicator]`.
+You should see: `[specific success indicator]`.
 
-   <details>
-     <summary>Output</summary>
+Hide complex output behind a details block:
+{{< details "Expected output">}}
 
-   ```text
-   ...
-   ```
-   </details>
+```text
+...
+```
+{{< /details >}}
 
-2. **Do the next thing**
+### Do the next thing
 
-   If needed, show the minimal config:
+If needed, show the minimal config:
 
-   ```yaml
-   # Key fields only
-   key: value
-   required: field
-   ```
+```yaml
+# Key fields only
+key: value
+required: field
+```
 
-3. **Verify**
+### Do the last thing
 
-   Show the shortest check that proves success:
+Show the shortest check that proves success:
 
-   ```bash
-   ocm <command> --check
-   ```
+```bash
+ocm <command> --check
+```
 
-   You should see: `[expected output]`. This confirms your setup is correct.
+You should see: `[expected output]`. This confirms your setup is correct.
 
-   <details>
-     <summary>Expected output</summary>
+{{< details "Expected output">}}
 
-   ```text
-   OK ...
-   ```
-   </details>
+```text
+OK ...
+```
+{{< /details >}}
 
 ## Troubleshooting
 
@@ -127,14 +122,6 @@ See [Diagram Color Guide]({{< relref "content_templates/template-tutorial.md#dia
 
 **Fix:** ...
 
-### Getting help
-
-If these solutions don't work:
-
-- [OCM Troubleshooting Guide]({{< relref "docs/troubleshooting/_index.md" >}})
-- [Community Support](link)
-- [Open an Issue](https://github.com/open-component-model/ocm/issues)
-
 ## Cleanup (optional)
 
 Remove resources created:
@@ -150,20 +137,22 @@ Remove resources created:
 
 ## Next steps
 
-- [How-to: <name>]({{< relref "docs/how-to/<file>.md" >}})
+Add links to related guides where you DO or LEARN more about the topic.
+
+- [Tutorial: <name>]({{< relref "docs/tutorials/<file>.md" >}})
 
 ## Related documentation
 
+Add links to related concepts and references that explain the WHY and provide more details.
+
 - [Concept: <name>]({{< relref "docs/concepts/<file>.md" >}})
-- [Tutorial: <name>]({{< relref "docs/tutorials/<file>.md" >}})
 - [Reference: <command>]({{< relref "docs/reference/<file>.md" >}})
 
 ---
 
 ## ✓ Before publishing
 
-Make sure to comply to our [CONTRIBUTING guide](../CONTRIBUTING.md),
-check the [Tutorial Writing Checklist](../CONTRIBUTING.md#how-to-guide-checklist),
+Make sure to comply to our [CONTRIBUTING guide](../CONTRIBUTING.md)
 and ensure the following:
 
 - [ ] Title starts with "How to..." or action verb (Configure/Deploy/Create/...)