From c47dc46d2cbd32159d8c0cf43f6f61ec997b86d8 Mon Sep 17 00:00:00 2001
From: Pedram Navid <1045990+PedramNavid@users.noreply.github.com>
Date: Mon, 19 Aug 2024 13:34:47 -0700
Subject: [PATCH] update templates to match automation guide

---
 .../content-templates/guide-no-steps.md       | 38 ++++++++-------
 .../content-templates/guide-with-steps.md     | 46 +++++++++----------
 2 files changed, 39 insertions(+), 45 deletions(-)

diff --git a/docs/docs-beta/content-templates/guide-no-steps.md b/docs/docs-beta/content-templates/guide-no-steps.md
index e49ae9405a926..9ffb954e78ccc 100644
--- a/docs/docs-beta/content-templates/guide-no-steps.md
+++ b/docs/docs-beta/content-templates/guide-no-steps.md
@@ -1,40 +1,38 @@
 ---
-title: ''
-description: ''
+title: 'Title that briefly describes what the guide is for'
+description: 'Description of the guide, useful for SEO and social media links'
 ---
 
-# [Title that briefly describes what the guide is for]
+Provide a brief introduction to the how-to guide. View [this article](https://diataxis.fr/how-to-guides/) for more information on how to write effective how-to guides. The intro should be no more than a few sentences.
+The title from the frontmatter will be used as the first heading in the guide, you don't need to include it in the intro.
 
-<!-- This section is a brief introduction into the guide's topic. -->
+## What you'll learn
 
-By the end of this guide, you will [a sentence or list about what will be achieved by the end of the guide].
+- A thing you'll learn, ex: "How to generate a token"
+- Another thing you'll learn, ex: "How to install this library"
+- One more thing you'll learn
 
----
-
-## Prerequisites
-
-<!-- This section lists the prerequisites users must complete before they should/can proceed with the guide. -->
+<details>
+  <summary>Prerequisites</summary>
 
 To follow the steps in this guide, you'll need:
 
-- A prerequisite, ex: "Familiarity with Asset definitions"
-- Another prerequisite, ex: "To install <this> library"
+- A prerequisite, ex: "Familiarity with [Asset definitions](/concepts/assets)"
+- Another prerequisite, ex: "To install this library"
 - One more
 
----
+</details>
 
 ## Title that describes this section
 
-<!--
-For section heaings:
+For section headings:
 
 - Guides can (and should) contain multiple sections, with each one being a small chunk of information. Break large topics into smaller topics, using subsequent headings (H3, H4, etc) as needed
 - Titles should describe an action, ex: "Generate a token"
 - Don't use gerunds (-ing) in titles, as it can cause issues with translation + SEO
--->
-
----
 
-## Related
+## Next steps
 
-[List of links to related content]
+- Add links to related content
+- Go deeper into [Understanding Automation](/concepts/understanding-automation)
+- Explore [Related Example](/)
diff --git a/docs/docs-beta/content-templates/guide-with-steps.md b/docs/docs-beta/content-templates/guide-with-steps.md
index c23598f5092cc..3e96b770524a0 100644
--- a/docs/docs-beta/content-templates/guide-with-steps.md
+++ b/docs/docs-beta/content-templates/guide-with-steps.md
@@ -1,49 +1,45 @@
 ---
-title: ''
-description: ''
+title: 'Title that briefly describes what the guide is for'
+description: 'Description of the guide that is useful for SEO and social media links'
 ---
 
-# [Title that briefly describes what the guide is for]
+Provide a brief introduction to the how-to guide. View [this article](https://diataxis.fr/how-to-guides/) for more information on how to write effective how-to guides. The intro should be no more than a few sentences.
+The title from the frontmatter will be used as the first heading in the guide, you don't need to include it in the intro.
 
-<!-- This section is a brief introduction into the guide's topic. -->
+## What you'll learn
 
-By the end of this guide, you will [a sentence or list about what will be achieved by the end of the guide].
+- A thing you'll learn, ex: "How to generate a token"
+- Another thing you'll learn, ex: "How to install this library"
+- One more thing you'll learn
 
----
-
-## Prerequisites
-
-<!-- This section lists the prerequisites users must complete before they should/can proceed with the guide. -->
+<details>
+  <summary>Prerequisites</summary>
 
 To follow the steps in this guide, you'll need:
 
-- A prerequisite, ex: "Familiarity with Asset definitions"
-- Another prerequisite, ex: "To install <this> library"
+- A prerequisite, ex: "Familiarity with [Asset definitions](/concepts/assets)"
+- Another prerequisite, ex: "To install this library"
 - One more
 
----
+</details>
 
 ## Step 1: Title that describes what this step will do {#step-1}
 
-<!--
-For section / step heaings:
+For section / step headings:
 
 - Titles should describe an action, ex: "Generate a token"
 - Don't use gerunds (-ing) in titles, as it can cause issues with translation + SEO
-- Each section heading should have an ID that includes the word 'step' and the number of the step, ex: {#step-1}
--->
+- Each section heading should have an identifier that includes the word 'step' and the number of the step, ex: {#step-1}
 
 ### Step 1.1: Title that describes a substep {#step-1-1}
 
-<!-- - If a step would benefit by being broken into smaller steps, follow this section's formatting
-- Each substep should get an H3 and start with Step N., followed by the number of the substep -->
-
----
+If a step would benefit by being broken into smaller steps, follow this section's formatting
+Each substep should get an H3 and start with Step N., followed by the number of the substep
 
 ## Step 2: Another step {#step-2}
 
----
-
-## Related
+## Next steps
 
-[List of links to related content]
+- Add links to related content
+- Go deeper into [Understanding Automation](/concepts/understanding-automation)
+- Explore [Related Example](/)