diff --git a/_docs/_contributing/content_types.md b/_docs/_contributing/content_types.md new file mode 100644 index 00000000000..a0d7d80d48e --- /dev/null +++ b/_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 + +``` + +{% 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 machine learning 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 %} diff --git a/_docs/_contributing/styling_examples.md b/_docs/_contributing/styling_examples.md index 7c4a0b022d4..da0a7d43ac0 100644 --- a/_docs/_contributing/styling_examples.md +++ b/_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 %} diff --git a/_docs/_contributing/templates.md b/_docs/_contributing/templates.md deleted file mode 100644 index b40bf3bc514..00000000000 --- a/_docs/_contributing/templates.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -nav_title: Templates -article: Templates -page_order: 4 ---- - -# Templates - -> You can use these templates 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 - -``` - -{% alert important %} -You can keep these comments in your file while writing, but you'll need to remove them before publishing. -{% endalert %} - -## Available templates - -### Basic - -{% multi_lang_include contributing/templates/basic.md %} - -### Technology partner - -{% multi_lang_include contributing/templates/technology_partner.md %} - -### Release notes - -{% multi_lang_include contributing/templates/release_notes.md %} - -## Modifying a template - -You can modify a template by following the steps outlined in these pages: - -- [Content management]({{site.baseurl}}/contributing/content_management/) -- [Metadata]({{site.baseurl}}/contributing/yaml_front_matter/metadata/) -- [Page layouts]({{site.baseurl}}/contributing/yaml_front_matter/page_layouts/) diff --git a/_includes/contributing/templates/basic.md b/_includes/contributing/templates/basic.md index f0fed17aed3..e5ccf2ba73d 100644 --- a/_includes/contributing/templates/basic.md +++ b/_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 +— # ARTICLE_TITLE - + > DESCRIPTION. -OPTIONAL_CONTEXT. +INTRODUCTION. ## Prerequisites @@ -26,21 +29,53 @@ Before you start, you'll need to complete the following: - ACTION_TO_COMPLETE - ACTION_TO_COMPLETE - -## SECTION_TITLE + +## How it works + +CONTENT. + + ## Integration CONTENT. - -## SECTION_TITLE + +## TASK_TO_COMPLETE + + +CONTENT. + ### Step 1: ACTION_TO_COMPLETE + CONTENT. ### Step 2: ACTION_TO_COMPLETE CONTENT. + +### REFERENCE_TO_ASSIST_WITH_ACTION + +CONTENT. + + +### Step 3: OPTIONAL_ACTION_TO_COMPLETE (optional) + +CONTENT. + +## Supported data types / Supported attributes / Supported events / Supported ETC. +CONTENT. + +## Considerations + +CONTENT. + + +## Troubleshooting + +### ISSUE_TO_TROUBLESHOOT +CONTENT. + ````` {% endraw %} {% enddetails %} \ No newline at end of file diff --git a/_includes/contributing/templates/explanation.md b/_includes/contributing/templates/explanation.md new file mode 100644 index 00000000000..66496893b22 --- /dev/null +++ b/_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 + + +> DESCRIPTION. + +INTRODUCTION. + + +## SECTION_NAME + +CONTENT. + + +## SECTION_NAME + +CONTENT. +``` +{% endraw %} +{% enddetails %} diff --git a/_includes/contributing/templates/how_to_guide.md b/_includes/contributing/templates/how_to_guide.md new file mode 100644 index 00000000000..09baf54203f --- /dev/null +++ b/_includes/contributing/templates/how_to_guide.md @@ -0,0 +1,63 @@ +{% 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 + + +> DESCRIPTION. + +INTRODUCTION. + + +## Prerequisites + +Before you start, you'll need to complete the following: + +- ACTION_TO_COMPLETE +- ACTION_TO_COMPLETE +- ACTION_TO_COMPLETE + + +## How it works + +CONTENT. + + +## TASK_TO_COMPLETE + + +CONTENT. + + +### Step 1: ACTION_TO_COMPLETE + + +CONTENT. + +### Step 2: ACTION_TO_COMPLETE + +CONTENT. + +### REFERENCE_TO_ASSIST_WITH_ACTION + +CONTENT. + + +### Step 3: OPTIONAL_ACTION_TO_COMPLETE (optional) + +CONTENT. + +## Supported data types / Supported attributes / Supported events / Supported ETC. +CONTENT. +`````` +{% endraw %} +{% enddetails %} diff --git a/_includes/contributing/templates/reference.md b/_includes/contributing/templates/reference.md new file mode 100644 index 00000000000..66496893b22 --- /dev/null +++ b/_includes/contributing/templates/reference.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 + + +> DESCRIPTION. + +INTRODUCTION. + + +## SECTION_NAME + +CONTENT. + + +## SECTION_NAME + +CONTENT. +``` +{% endraw %} +{% enddetails %} diff --git a/_includes/contributing/templates/release_notes.md b/_includes/contributing/templates/release_notes.md index 748367bd5fa..d2a18ae9122 100644 --- a/_includes/contributing/templates/release_notes.md +++ b/_includes/contributing/templates/release_notes.md @@ -1,5 +1,3 @@ -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/). - {% details Show template %} {% raw %} `````markdown diff --git a/_includes/contributing/templates/tutorial.md b/_includes/contributing/templates/tutorial.md new file mode 100644 index 00000000000..3feb650a753 --- /dev/null +++ b/_includes/contributing/templates/tutorial.md @@ -0,0 +1,36 @@ +{% details Show template %} +{% raw %} +```markdown +--- +nav_title: NAV_TITLE +article_title: Tutorial: WHAT_THE_USER_WILL_DO +description: "SHORT_DESCRIPTION." +alias: /OPTIONAL_SHORT_ARTICLE_TITLE/ +page_type: tutorial +layout: OPTIONAL_LAYOUT_FILE +—-- + +# Tutorial: WHAT_THE_USER_WILL_DO + + +> DESCRIPTION. + +INTRODUCTION. + + +When you’re finished with this tutorial, you’ll be able to: + +- LEARNING_OBJECTIVE +- LEARNING_OBJECTIVE +- LEARNING_OBJECTIVE + + + +- Navigate the Braze Docs GitHub repository +- Make changes using the GitHub website or your local environment +- Create pull requests (PRs) +- Preview your changes in a test site +- Request a review from the Braze Docs team +``` +{% endraw %} +{% enddetails %} diff --git a/assets/img/contributing/content_types/explanation_example.png b/assets/img/contributing/content_types/explanation_example.png new file mode 100644 index 00000000000..b14d36c5eb3 Binary files /dev/null and b/assets/img/contributing/content_types/explanation_example.png differ diff --git a/assets/img/contributing/content_types/explanation_header_syntax_example.png b/assets/img/contributing/content_types/explanation_header_syntax_example.png new file mode 100644 index 00000000000..5027c832956 Binary files /dev/null and b/assets/img/contributing/content_types/explanation_header_syntax_example.png differ diff --git a/assets/img/contributing/content_types/how_to_guide_example.png b/assets/img/contributing/content_types/how_to_guide_example.png new file mode 100644 index 00000000000..9716dd53564 Binary files /dev/null and b/assets/img/contributing/content_types/how_to_guide_example.png differ diff --git a/assets/img/contributing/content_types/reference_example.png b/assets/img/contributing/content_types/reference_example.png new file mode 100644 index 00000000000..659d2bb1a73 Binary files /dev/null and b/assets/img/contributing/content_types/reference_example.png differ diff --git a/assets/img/contributing/content_types/tutorial_example.png b/assets/img/contributing/content_types/tutorial_example.png new file mode 100644 index 00000000000..a9df2aefdd0 Binary files /dev/null and b/assets/img/contributing/content_types/tutorial_example.png differ diff --git a/assets/js/broken_redirect_list.js b/assets/js/broken_redirect_list.js index 9f45f247534..33ae7b2bf8e 100644 --- a/assets/js/broken_redirect_list.js +++ b/assets/js/broken_redirect_list.js @@ -1103,6 +1103,7 @@ validurls['/docs/help/help_articles/docs/contribution'] = '/docs/contributing/ho validurls['/docs/hidden/wip_partnerships/wip_guidelines'] = '/docs/contributing/home/'; validurls['/docs/hidden/wip_partnerships/partnership_template'] = '/docs/contributing/templates/#technology-partner'; validurls['/docs/help/help_articles/docs/contribution/'] = '/docs/contributing/home/'; +validurls['/docs/contributing/templates/'] = '/docs/contributing/content_types/'; validurls['/docs/user_guide/administrative/app_settings/manage_your_braze_users/deleting_users_from_your_account/#deleting-braze-account-users'] = '/docs/user_guide/administrative/app_settings/manage_your_braze_users/adding_users_to_your_dashboard/#deleting-braze-users';