chore: Add Templates for tutorials and how-to docs following diataxis methodology (#713)

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

<!-- markdownlint-disable MD041 -->
#### What this PR does / why we need it
Add templates for tutorials and how-tos.

---------

Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
Co-authored-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>

Author: morri-son

.github/config/wordlist.txt

@@ -453,3 +453,6 @@ monorepo
 repos
 callout
 diataxis
+callouts
+shortcode
+shortcodes

README.md

@@ -27,9 +27,10 @@ All content lives under the `content` directory and is organized by section.
 | `content/_index.md`            | Site landing page content                                    |
 | `content/docs/concepts`        | Concept explanations                                         |
 | `content/docs/getting-started` | Getting Started guides                                       |
+| `content/docs/how-to`          | Task-focused how-to guides                                   |
 | `content/docs/overview`        | Overview and introductory information                        |
 | `content/docs/reference`       | Reference and CLI documentation (mounted via module imports) |
-| `content/docs/tutorials`       | Tutorials                                                    |
+| `content/docs/tutorials`       | Step-by-step tutorials                                       |
 | `content/community`            | Community information                                        |
 
 Versioned snapshot folders live under `content_versioned/`:
@@ -58,7 +59,15 @@ logo: "📄"
 weight: 92
 ```
 
-There are templates for frontmatter of [standard pages](content_templates/new-doc.md) and [_index.md](content_templates/_index.md) of overview pages.
+### Documentation Templates
+
+We follow the **Diataxis** documentation framework to structure our content. The following templates are available in `content_templates/`:
+
+- [**Tutorial Template**](content_templates/template-tutorial.md) – For learning-oriented, step-by-step guides
+- [**How-To Guide Template**](content_templates/template-how-to.md) – For task-focused, goal-oriented instructions
+- [**Section Overview Template**](content_templates/_index.md) – For section `_index.md` files
+
+Use these templates when creating new documentation to ensure consistency and best practices.
 
 ### Standard Content Pages
 

content_templates/new-doc.md

@@ -0,0 +1,142 @@
+---
+title: "TEMPLATE: How-to Title"
+description: "A task-focused recipe: do X in OCM."
+weight: 999
+toc: true
+---
+
+## Goal
+
+One sentence: what you will achieve.
+
+{{< callout type="note" >}}
+**You will end up with**
+
+- A concrete outcome (artifact/config/state)
+- A verifiable success condition
+{{< /callout >}}
+
+**Estimated time:** ~X minutes
+
+## Prerequisites
+
+- [OCM CLI]({{< relref "docs/getting-started/install.md" >}}) installed
+- Access to the required repository/service
+- Required credentials/keys available
+
+{{< callout type="warning" >}}
+⚠️ **Preconditions:** Mention anything that would cause data loss or unexpected changes.
+{{< /callout >}}
+
+## Steps
+
+1. **Do the first thing**
+
+   Brief explanation (1–2 sentences max). Link to concepts for "why"—don't explain inline.
+
+   ```bash
+   ocm <command> <args>
+   ```
+
+   You should see: `[specific success indicator]`.
+
+   <details>
+     <summary>Output</summary>
+
+   ```text
+   ...
+   ```
+   </details>
+
+2. **Do the next thing**
+
+   If needed, show the minimal config:
+
+   ```yaml
+   # Key fields only
+   key: value
+   required: field
+   ```
+
+3. **Verify**
+
+   Show the shortest check that proves success:
+
+   ```bash
+   ocm <command> --check
+   ```
+
+   You should see: `[expected output]`. This confirms your setup is correct.
+
+   <details>
+     <summary>Expected output</summary>
+
+   ```text
+   OK ...
+   ```
+   </details>
+
+## Troubleshooting
+
+### Symptom: [Specific error message]
+
+**Cause:** One sentence explaining why.
+
+**Fix:**
+
+```bash
+# Fix command
+...
+```
+
+### Symptom: [Another issue]
+
+**Cause:** ...
+
+**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:
+
+```bash
+# Cleanup commands
+...
+```
+
+{{< callout type="warning" >}}
+⚠️ This will delete [what will be deleted].
+{{< /callout >}}
+
+## Next steps
+
+- [Concept: Relevant Concept]({{< relref "docs/concepts/<file>.md" >}}) — understand why
+- [Tutorial: Related Tutorial]({{< relref "docs/tutorials/<file>.md" >}}) — learn by doing
+- [Reference: Command Docs]({{< relref "docs/reference/<file>.md" >}}) — complete details
+
+## Related documentation
+
+- [Concept: <name>]({{< relref "docs/concepts/<file>.md" >}})
+- [Tutorial: <name>]({{< relref "docs/tutorials/<file>.md" >}})
+- [Reference: <command>]({{< relref "docs/reference/<file>.md" >}})
+
+---
+
+## ✓ Before publishing
+
+- [ ] Action verb title (Configure/Deploy/Create)
+- [ ] Simple numbered lists (use `{{< steps >}}` only if 5+ complex steps)
+- [ ] Success indicators after each step
+- [ ] Links to concepts (never inline "why" explanations)
+- [ ] Use `{{< tabs >}}` for variants (different approaches, platforms, configurations)
+- [ ] Troubleshooting with symptom-cause-fix
+- [ ] Working relref links
+- [ ] Realistic time estimate