-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
update templates to match automation guide
- Loading branch information
1 parent
33b1826
commit c47dc46
Showing
2 changed files
with
39 additions
and
45 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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](/) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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](/) |