BD-3069 Diataxis templates

_docs/_contributing/content_types.md

@@ -0,0 +1,183 @@
+---
+nav_title: Content Types
+article: Content Types
+page_order: 4
+---
+
+# Content types
+
+> Braze Docs follows the [Diátaxis framework](https://diataxis.fr/), which organizes pages into one of four content types, each one meeting a different learning objective. While a single page on Braze Docs may contain multiple content types, each type should get a dedicated section on the page.
+
+These are the content types you'll find on Braze Docs:
+
+| Documentation type | Purpose |
+| --- | --- |
+| [How-to guides](#how-to-guides) | Help the user **apply knowledge**. |
+| [Tutorials](#tutorials) | Help the user **acquire knowledge**. |
+| [References](#references) | Provide the user with **technical knowledge**. |
+| [Explanations](#explanations) | Broaden the user’s **contextual knowledge**. |
+| [Release notes](#release-notes) | Inform the user about product updates. |
+
+## Using templates
+
+Each content type has a dedicated template you can use to create [pages]({{site.baseurl}}/contributing/content_management/pages/) or [sections]({{site.baseurl}}/contributing/content_management/sections/) on Braze Docs.
+
+Read HTML comments like the following to learn more about each section in a template:
+
+```markdown
+<!-- Here's an HTML comment! -->
+```
+
+{% alert important %}
+You can keep these comments in your file while writing, but you'll need to remove them before publishing.
+{% endalert %}
+
+## Content types
+
+### How-to guides
+
+How-to guides are action-based, chronological steps that show users how to complete a specific task. For an example, see [Creating a Content Card]({{site.baseurl}}/user_guide/message_building_by_channel/content_cards/create/):
+
+![Screenshot of the "Creating a Content Card" page.]({% image_buster /assets/img/contributing/content_types/how_to_guide_example.png %}){: style="max-width:70%;"}
+
+{% multi_lang_include contributing/templates/how_to_guide.md %}
+
+#### Guidelines
+
+- Cover only what the user needs to know to take action. 
+- Only cover the best or recommended way to complete the task. Do not give document alternative methods.
+- Only include [reference material](#references) that's vital to the end-user's goal, such as a list of options a user can select during a step.
+- Link out to references that are longer than reasonable to include in the same article, such as [Segmentation filters]({{site.baseurl}}/user_guide/engagement_tools/segments/segmentation_filters/).
+- Avoid providing troubleshooting steps. Instead, you can include this information in a another section on this page or a separate article.
+
+#### Header syntax
+
+H2 headers (`##` in Markdown) should be action-oriented and reflect the general goal for this step. If there's any optional steps, prepend `(Optional)` to the header. For example:
+
+{% raw %}
+```
+## Creating a page
+
+1. Open the relevant directory in `braze-docs`.
+2. Create a new Markdown file for your page.
+3. Ensure your filename follows our [naming guidelines](#naming-guidelines).
+4. (Optional) You can generate a preview by running `rake` in your terminal.
+```
+{% endraw %}
+
+For long or complicated steps, use nested headers to group related steps. If there's any optional steps, append `(optional)` to the header. For example:
+
+{% raw %}
+``````markdown
+## Creating a page
+
+### Step 1: Create a new file
+
+Open the relevant directory, then create a new Markdown file for your page.
+
+```plaintext
+PAGE_TITLE.md
+```
+
+### Step 2: Add a template
+
+Copy and paste one of the following templates into your Markdown file. For more information, see [Templates]({{site.baseurl}}/contributing/templates/).
+
+### Step 3: Generate a preview (optional)
+
+To generate a preview, open your terminal and run the following command:
+
+```bash
+rake
+```
+``````
+{% endraw %}
+
+### Tutorials
+
+Tutorials are learning-oriented practical lessons. They focus on what the user learns, such as becoming familiar with terminology, how things interact, how to use commands, and similar. For an example, see [Rules-based recommendations]({{site.baseurl}}/user_guide/sage_ai/recommendations/rules_based_recommendations/):
+
+![Screenshot of the "Rules-based recommendations page.]({% image_buster /assets/img/contributing/content_types/tutorial_example.png %}){: style="max-width:70%;"}
+
+{% multi_lang_include contributing/templates/tutorial.md %}
+
+#### Guidelines
+
+- Create a guided step-by-step activity or scenario for the user to follow or roleplay. 
+- Assume that the user has little to no familiarity with the platforms, tools, or workflows used during the activity.
+
+{% alert tip %}
+Provide ready-made assets for the user to input that aren't the key focus of your tutorial. For example, you could provide photos, messaging, and Liquid coding for a tutorial that teaches users how to use a variety of features when creating a campaign.
+{% endalert %}
+
+##### Header syntax
+
+The title header should be prepended with `Tutorial:` and generally describe what the user will do or create. For example, "Tutorial: Your first contribution". 
+
+### References
+
+References are information-oriented content. They focus on providing the user with objective, authoritative, and technical knowledge. For an example, see [Message engagement events]({{site.baseurl}}/user_guide/data_and_analytics/braze_currents/event_glossary/message_engagement_events/) (events glossary).
+
+![Screenshot of the "Message engagement events" page.]({% image_buster /assets/img/contributing/content_types/reference_example.png %}){: style="max-width:70%;"}
+
+{% multi_lang_include contributing/templates/reference.md %}
+
+#### Guidelines
+
+- Create technical descriptions or information that are necessary to complete a task.
+- Organize the information alphabetically, categorically, or hierarchically.
+- Put references in their respective articles unless they're longer than seems appropriate for a single article or will be referenced by multiple articles. 
+    - If they're only referenced by a single how-to guide and long enough to disrupt the flow of the steps, you can [make them collapsible]({{site.baseurl}}/contributing/styling_examples/#collapsible-content).
+
+##### Header syntax
+
+Topmost should be nouns. For example, [Editor blocks]({{site.baseurl}}/user_guide/message_building_by_channel/email/drag_and_drop/dnd_editor_blocks/) has the following names for its references:
+
+![Screenshot of the in-page table of contents for the "Editor Blocks" page. Headings include: Types (H2), Properties (H2), Title (H3), Paragraph (H3), List (H3), Button (H3), Divider (H3), Spacer (H3), Image (H3), Video (H3), Social (H3), Icons (H3), HTML (H3), Menu (H3).]({% image_buster /assets/img/contributing/content_types/explanation_header_syntax_example.png %}){: style="max-width:25%;"}
+
+### Explanations
+
+Explanations are understanding-oriented content. They focus on improving the user’s conceptual understanding. For an example, see [Getting started: Braze overview]({{site.baseurl}}/user_guide/getting_started/overview/).
+
+![Screenshot of the "Getting started: Braze overview" page.]({% image_buster /assets/img/contributing/content_types/explanation_example.png %}){: style="max-width:70%;"}
+
+{% multi_lang_include contributing/templates/explanation.md %}
+
+#### Guidelines
+
+- Create textual or visual descriptions of concepts, such as how data travels between features, third-party partners, tools, and similar.
+- Discuss how features and techniques can benefit users.
+- Place explanations in the most relevant article. For example, a basic feature article might have an explanation called "How it works" that describes that feature's workflow. 
+- Consider placing explanations that are too broad to fit into only one article onto a landing page for a general topic, such as [Campaigns]({{site.baseurl}}/user_guide/engagement_tools/campaigns).
+
+{% alert tip %}
+Even though explanations aren't telling users what to do to achieve a specific outcome, you can broadly describe chronological steps to acheive a general goal (such as using A/B testing to improve your messaging). Don't go into the same detail you would for a [how-to guide](#how-to-guides) or [tutorial](#tutorials).
+{% endalert %}
+
+##### Header syntax
+
+H1 headers (`#` in Markdown) are formatted as `About TOPIC_NAME`. If the explanation is a subsection on a page of a different content type, you can tweak the syntax as long as it implies **Explanation** rather than **How-to**. Here are some examples:
+
+- `About TOPIC_NAME`
+- `TOPIC_NAME overview`
+- `How TOPIC works`
+- `How TOPIC is handled`
+- `What does Braze check?`
+
+### Release notes
+
+Release notes are a monthly compilation of product updates in Braze. Each update is placed under one of the following categories:
+
+| Category               | Description                                                             |
+|------------------------|-------------------------------------------------------------------------|
+| Data flexibility       | Updates on improving data structuring, storage, and access.             |
+| Unlocking creativity   | Features that enhance user creativity within the platform.              |
+| Robust channels        | Updates on the reliability and scalability of communication channels.   |
+| AI and ML automation   | Updates on AI and ML capabilities within the platform.                  |
+| New Braze partnerships | Introduces new integrations with other platforms and services.          |
+| SDK updates            | Lists new SDKs or updates, including breaking changes and new features. |
+{: .reset-td-br-1 .reset-td-br-2}
+
+You can use this template to create release notes for Braze Docs. For an example, see [January 9, 2024 release]({{site.baseurl}}/help/release_notes/2024/1_9_24/).
+
+{% multi_lang_include contributing/templates/release_notes.md %}

_docs/_contributing/styling_examples.md

@@ -524,7 +524,7 @@ video_source: youtube
 {% endtab %}
 {% endtabs %}
 
-## Collapsible Content Test
+## Collapsible Content Test {#collapsible-content}
 {% tabs %}
 {% tab Styling %}
 {% details Click me to Expand %}

_includes/contributing/templates/basic.md

@@ -1,4 +1,4 @@
-You can use this template to create any page or section for Braze Docs. For an example, see [Generating a preview]({{site.baseurl}}/contributing/generating_a_preview/).
+You can use this template to create any page or section for Braze Docs. For an example, see [Generating a preview]({{site.baseurl}}/contributing/generating_a_preview/). For guidelines on the documentation types used within the article, see [Page types]({{site.baseurl}}/contributing/page_types/).
 
 {% details Show template %}
 {% raw %}
@@ -7,15 +7,18 @@ You can use this template to create any page or section for Braze Docs. For an e
 nav_title: NAV_TITLE
 article_title: ARTICLE_TITLE
 description: "SHORT_DESCRIPTION."
----
+alias: /OPTIONAL_SHORT_ARTICLE_TITLE/
+page_type: reference
+layout: OPTIONAL_LAYOUT_FILE
+—
 
 <!-- The title of your page, used to render the in-page title. -->
 # ARTICLE_TITLE
 
-<!-- The description starts with a '>' character and contains an overview of what will be covered. Optionally, in a following paragraph, you can contextualize the topic at a high-level. -->
+<!-- The overview starts with a '>' character and discusses what will be covered. In an optional following paragraph, contextualize the topic at a high-level in an introduction. -->
 > DESCRIPTION.
 
-OPTIONAL_CONTEXT.
+INTRODUCTION.
 
 <!-- The prerequisites for this task. If no prerequisites are required, you can remove this section. -->
 ## Prerequisites
@@ -26,21 +29,53 @@ Before you start, you'll need to complete the following:
 - ACTION_TO_COMPLETE
 - ACTION_TO_COMPLETE
 
-<!-- An example section. You may add subsections, images, and links as needed. -->
-## SECTION_TITLE
+<!-- An optional, brief explanation of how the feature workflow looks. -->
+## How it works
+
+CONTENT.
 
+<!-- Walk a user through integrating and turning on the feature. -->
+ ## Integration
 CONTENT.
 
-<!-- An example section with subsections. You may add addtional subsections, images, and links as needed. -->
-## SECTION_TITLE
+<!-- A how-to guide with nested steps. -->
+## TASK_TO_COMPLETE
+
+<!-- Optional overview of the task. -->
+CONTENT.
 
+<!-- Action-oriented header that describes the step’s goal. -->
 ### Step 1: ACTION_TO_COMPLETE
 
+<!-- Use number bullets or paragraphs to describe how to complete this action -->
 CONTENT.
 
 ### Step 2: ACTION_TO_COMPLETE
 
 CONTENT.
+<!-- Optional references, such as supported data types, fields, definitions, and similar. -->
+### REFERENCE_TO_ASSIST_WITH_ACTION
+
+CONTENT.
+
+<!-- For optional steps, add “(optional)” to the end of the header. -->
+### Step 3: OPTIONAL_ACTION_TO_COMPLETE (optional)
+
+CONTENT.
+<!-- An optional section for what is supported. Add nested headers to be more specific. -->
+## Supported data types / Supported attributes / Supported events / Supported ETC.
+CONTENT.
+<!-- An optional section with important considerations for users to review before using the feature. -->
+## Considerations
+
+CONTENT.
+
+<!-- An optional section guiding users through troubleshooting common issues. -->
+## Troubleshooting
+
+### ISSUE_TO_TROUBLESHOOT
+CONTENT.
+
 `````
 {% endraw %}
 {% enddetails %}

_includes/contributing/templates/explanation.md

@@ -0,0 +1,31 @@
+{% details Show template %}
+{% raw %}
+```markdown
+---
+nav_title: NAV_TITLE
+article_title: ARTICLE_TITLE
+description: "SHORT_DESCRIPTION."
+alias: /OPTIONAL_SHORT_ARTICLE_TITLE/
+page_type: reference
+layout: OPTIONAL_LAYOUT_FILE
+—--
+
+# ARTICLE_TITLE
+
+<!-- The overview starts with a '>' character and discusses what will be covered. In an optional following paragraph, contextualize the topic at a high-level in an introduction. -->
+> DESCRIPTION.
+
+INTRODUCTION.
+
+<!-- An optional section for organizing the page. -->
+## SECTION_NAME
+
+CONTENT.
+
+<!-- An optional section for organizing the page. -->
+## SECTION_NAME
+
+CONTENT.
+```
+{% endraw %}
+{% enddetails %}