Skip to content

Content types

Braze Docs follows the Diátaxis framework, 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 Help the user apply knowledge.
Tutorials Help the user acquire knowledge.
References Provide the user with technical knowledge.
Explanations Broaden the user’s contextual knowledge.
Release notes Inform the user about product updates.

Using templates

Each content type has a dedicated template you can use to create pages or sections on Braze Docs.

Read HTML comments like the following to learn more about each section in a template:

1

<!-- Here's an HTML comment! -->

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:

Screenshot of the "Creating a Content Card" page.

Show template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

---
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.

<!-- The prerequisites for this task. If no prerequisites are required, you can remove this section. -->
## Prerequisites

Before you start, you'll need to complete the following:

- ACTION_TO_COMPLETE
- ACTION_TO_COMPLETE
- ACTION_TO_COMPLETE

<!-- An optional, brief explanation of how the feature workflow looks. -->
## How it works

CONTENT.

<!-- 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.

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 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.
  • 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:

1
2
3
4
5
6

## Creating a page

1. Open the relevant directory in `braze-docs`.
2. Create a new Markdown file for your page.
3. Use a filename that follows our [naming guidelines](#naming-guidelines).
4. (Optional) You can generate a preview by running `rake` in your terminal.

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:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

## 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
```

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:

Screenshot of the "Rules-based recommendations page.

Show template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

---
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

<!-- 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.

<!-- Introduce the tutorial with the following format:-->
When you’re finished with this tutorial, you’ll be able to:

- LEARNING_OBJECTIVE
- LEARNING_OBJECTIVE
- LEARNING_OBJECTIVE

<!-- Replace each `LEARNING_OBJECTIVE` with something the user will broadly learn how to do during the tutorial. For example, a tutorial that walks a user through creating their first contribution to the Braze Docs site might have the following objectives:-->

- 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

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.
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 (events glossary).

Screenshot of the "Message engagement events" page.

Show template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

---
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.

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.
Header syntax

Topmost should be nouns. For example, 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).

Explanations

Explanations are understanding-oriented content. They focus on improving the user’s conceptual understanding. For an example, see Getting started: Braze overview.

Screenshot of the "Getting started: Braze overview" page.

Show template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

---
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.

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.
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.

You can use this template to create release notes for Braze Docs. For an example, see January 9, 2024 release.

Show template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

---
nav_title: ARTICLE_TITLE
description: "This article contains release notes for DATE."
page_order: ORDER_NUMBER
page_type: reference
---

<!-- The title should include the date the release note is made live. For example, "February 21, 2024 release". -->
# MONTH DAY, YEAR release

<!-- Fill out the following four sections ("Data flexibility," "Unlocking creativity," "Robust channels," and "AI and ML automation") using the example section under the next HTML comment. -->
## Data flexibility

CONTENT.

## Unlocking creativity

CONTENT.

## Robust channels

CONTENT.

## AI and ML automation

CONTENT.

<!-- An example section containing "Release type" includes for each section. You may add addtional sections, subsections, includes, images, and links as needed. -->
## SECTION_TITLE

CONTENT.

### SUBSECTION_TITLE

{% multi_lang_include release_type.md release="Early access" %}

CONTENT.

### SUBSECTION_TITLE

{% multi_lang_include release_type.md release="General availability" %}

CONTENT.

### SUBSECTION_TITLE

{% multi_lang_include release_type.md release="Beta" %}

CONTENT.

### SUBSECTION_TITLE

CONTENT.

<!-- Use this section to highlight new Braze parternships by including an overview of each integration and a link to the related partner page on Braze Docs. -->
## New Braze partnerships

### PARTNER_NAME

CONTENT.

### PARTNER_NAME

CONTENT.

<!-- Use this section list any new SDKs or SDK updates that are already released. -->
## SDK updates

The following SDK updates have been released. Breaking updates are listed below; all other updates can be found by checking the corresponding SDK changelogs.

- [SDK_NAME](LINK_TO_GITHUB_CHANGELOG)
    - OPTIONAL_CONTEXT.
- [SDK_NAME](LINK_TO_GITHUB_CHANGELOG)
- [SDK_NAME](LINK_TO_GITHUB_CHANGELOG)
  Edit this page on GitHub
HOW HELPFUL WAS THIS PAGE?
New Stuff!