This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Docs contributing guide

How to contribute to the Dapr docs

1: Contributors guide
2: Maintainer guide
3: Suggested Dapr docs templates

3.1: Conceptual article template
3.2: Quickstart guide template
3.3: How-to guide template

1 - Contributors guide

Get started with contributing to the Dapr docs

In this guide, you’ll learn how to contribute to the Dapr docs repository. Since Dapr docs are published to docs.dapr.io, you must make sure your contributions compile and publish correctly.

Prerequisites

Before contributing to the Dapr docs:

Review the guidance around general Dapr project contributions.
Install and set up your local environment with Hugo with the Docsy theme. Follow the instructions in the repository README.md.
Fork and clone the docs repository.

Branch guidance

The Dapr docs handles branching differently than most code repositories. Instead of a main branch, every branch is labeled to match the major and minor version of a runtime release. For the full list visit the Docs repo

Generally, all of your docs updates should point to docs branch for the latest release of Dapr. The latest release is the default branch [https://github.com/dapr/docs]. For example, if you are fixing a typo, adding notes, or clarifying a point, make your changes into the default Dapr branch.

For any docs changes applicable to a release candidate or a pre-release version of the docs, point your changes into that particular branch. For example, if you are documenting an upcoming change to a component or the runtime, make your changes to the pre-release branch.

Style and tone

Style and tone conventions should be followed throughout all Dapr documentation for consistency across all docs:

Style/Tone	Guidance
Casing	Use upper case only: At the start of a sentence or header For proper nouns, including names of technologies (Dapr, Redis, Kubernetes etc.)
Headers and titles	Headers and titles must be brief, but descriptive and clear.
Use simple sentences	Write easy-to-read, scannable sentences. Tip: Skip the formal tone and write as if you were talking directly to the reader.
Avoid the first person	Instead of first person “I”, “we”, and “our”, use second person “you” and “your”.
Assume a “new developer” audience	Some seemingly obvious steps to an experienced developer might not be as obvious to a new developer. Give the reader more explicit, thorough instructions.
Use present tense	Avoid sentences like “this command will install Redis”. Instead, use “This command installs Redis”.

Diagrams and images

Diagrams and images are invaluable visual aids for documentation pages. Use the diagram style and icons in the Dapr Diagrams template deck.

The process for creating diagrams for your documentation:

Download the Dapr Diagrams template deck to use the icons and colors.
Add a new slide and create your diagram.
Screen capture the diagram as high-res PNG file and save in the images folder.
Name your PNG files using the convention of a concept or building block so that they are grouped.

For example: service-invocation-overview.png.
For more information on calling out images using shortcode, see the Images guidance section below.

Add the diagram to the appropriate section in your documentation using the HTML <image> tag.
In your PR, comment the diagram slide (not the screen capture) so it can be reviewed and added to the diagram deck by maintainers.

Contributing a new docs page

If you’re creating a new article, make sure you:

Place the new document in the correct place in the hierarchy.
Avoid creating new sections. Most likely, the proper place is already in the docs hierarchy.
Include complete Hugo front-matter.

Select the topic type below to view a suggested template to help you get started.

Topic type	What is it?
Concept	Answers the question, “What problems does this help me solve?” Avoid repeating the API or component spec; provide more details.
Quickstart	Provides a “Five minutes to wow” experience. Walk the reader quickly through a feature or API and how it works in a controlled example.
How-to	Provides a detailed, practical step-by-step through a Dapr feature or technology. Encourage the reader to try with their own scenario, rather than the controlled scenario provided in a quickstart.

Requirements for docs.dapr.io

Make sure your contribution doesn’t break the website build. The way Hugo builds the website requires following the guidance below:

Files and folder names

File and folder names should be globally unique. - \service-invocation - service-invocation-overview.md

Front-matter

Front-matter is what takes regular markdown files and upgrades them into Hugo compatible docs for rendering into the nav bars and ToCs.

Every page needs a section at the top of the document like this:

---
type: docs
title: "TITLE FOR THE PAGE"
linkTitle: "SHORT TITLE FOR THE NAV BAR"
weight: (number)
description: "1+ SENTENCES DESCRIBING THE ARTICLE"
---

Example

---
type: docs
title: "Service invocation overview"
linkTitle: "Overview"
weight: 10
description: "A quick overview of Dapr service invocation and how to use it to invoke services within your application"
---

Weight determines the order of the pages in the left sidebar, with 0 being the top-most.

Front-matter should be completed with all fields including type, title, linkTitle, weight, and description.

title should be 1 sentence, no period at the end
linkTitle should be 1-3 words, with the exception of How-to at the front.
description should be 1-2 sentences on what the reader will learn, accomplish, or do in this doc.

As per the styling conventions, titles should only capitalize the first word and proper nouns, with the exception of “How-To:”

“Getting started with Dapr service invocation”
“How-To: Setup a local Redis instance”

Referencing other pages

Hugo ref and relref shortcodes are used to reference other pages and sections. These shortcodes also allow the build to break if a page is incorrectly renamed or removed.

For example, this shortcode, written inline with the rest of the markdown page, will link to the _index.md of the section/folder name:

{{% ref "folder" %}}

While this shortcode will link to a specific page:

{{% ref "page" %}}

All pages and folders need to have globally unique names in order for the ref shortcode to work properly. If there are duplicate names, the build will break and an error will be thrown.

Referencing sections in other pages

To reference a specific section in another page, add #section-short-name to the end of your reference.

As a general rule, the section short name is the text of the section title, all lowercase, with spaces changed to “-”. You can check the section short name by:

Visiting the website page.
Clicking the link icon (🔗) next to the section.
Seeing how the URL renders in the nav bar.
Copying the content after the “#” for your section shortname.

As an example, for this specific section, the complete reference to the page and section would be:

{{% ref "contributing-docs#referencing-sections-in-other-pages" %}}

Shortcodes

The following are useful shortcodes for writing Dapr documentation

Images

The markdown spec used by Docsy and Hugo does not give an option to resize images using markdown notation. Instead, raw HTML is used.

Begin by placing images under /daprdocs/static/images with the naming convention of [page-name]-[image-name].[png|jpg|svg].

Then link to the image using:

<img src="/images/[image-filename]" width=1000 alt="Description of image">

Don’t forget to set the alt attribute to keep the docs readable and accessible.

Example

This HTML will display the dapr-overview.png image on the overview.md page:

<img src="/images/overview-dapr-overview.png" width=1000 alt="Overview diagram of Dapr and its building blocks">

Tabbed content

Tabs are made possible through Hugo shortcodes.

The overall format is:








  
      
    

      
    



    
        [Content for Tab1]

    
    
        [Content for Tab2]

All content you author will be rendered to markdown, so you can include images, code blocks, YouTube videos, and more.

Example










  
      
    

      
    

      
    



    
        powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"
wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash
brew install dapr/tap/dapr-cli

This example will render to this:

powershell -Command "iwr -useb https://raw.githubusercontent.com/dapr/cli/master/install/install.ps1 | iex"

wget -q https://raw.githubusercontent.com/dapr/cli/master/install/install.sh -O - | /bin/bash

brew install dapr/tap/dapr-cli

YouTube videos

Hugo can automatically embed YouTube videos using a shortcode:

{{% youtube [VIDEO ID] %}}

Example

Given the video https://youtu.be/dQw4w9WgXcQ

The shortcode would be:

{{% youtube dQw4w9WgXcQ %}}

Buttons

To create a button in a webpage, use the button shortcode.

An optional “newtab” parameter will indicate if the page should open in a new tab. Options are “true” or “false”. Default is “false”, where the page will open in the same tab.

Link to an external page

{{% button text="My Button" link="https://example.com" %}}

My Button

Link to another docs page

You can also reference pages in your button as well:

{{% button text="My Button" page="contributing" newtab="true" %}}

My Button

Button colors

You can customize the colors using the Bootstrap colors:

{{% button text="My Button" link="https://example.com" color="primary" %}}
{{% button text="My Button" link="https://example.com" color="secondary" %}}
{{% button text="My Button" link="https://example.com" color="success" %}}
{{% button text="My Button" link="https://example.com" color="danger" %}}
{{% button text="My Button" link="https://example.com" color="warning" %}}
{{% button text="My Button" link="https://example.com" color="info" %}}

My Button

References

Docsy authoring guide

Translations

The Dapr Docs supports adding language translations into the docs using git submodules and Hugo’s built in language support.

You can find an example PR of adding Chinese language support in PR 1286.

Steps to add a language:

Open an issue in the Docs repo requesting to create a new language-specific docs repo

Once created, create a git submodule within the docs repo:

git submodule add <remote_url> translations/<language_code>

Add a language entry within daprdocs/config.toml:

 [languages.<language_code>]
   title = "Dapr Docs"
   weight = 3
   contentDir = "content/<language_code>"
   languageName = "<language_name>"

Create a mount within daprdocs/config.toml:

[[module.mounts]]
  source = "../translations/docs-<language_code>/content/<language_code>"
  target = "content"
  lang = "<language_code>"

Repeat above step as necessary for all other translation directories.

Next steps

Get started by copying and working from one of the Dapr doc templates.

2 - Maintainer guide

Get started as a Dapr docs maintainer and approver.

In this guide, you’ll learn how to perform routine Dapr docs maintainer and approver responsibilities. In order to successfully accomplish these tasks, you need either approver or maintainer status in the dapr/docs repo.

To learn how to contribute to Dapr docs, review the Contributor guide.

Branch guidance

The Dapr docs handles branching differently than most code repositories. Instead of a main branch, every branch is labeled to match the major and minor version of a runtime release.

For the full list, visit the Docs repo.

Read the contributor’s guide for more information about release branches.

Upmerge from current release branch to the pre-release branch

As a docs approver or maintainer, you need to perform routine upmerges to keep the pre-release branch aligned with updates to the current release branch. It is recommended to upmerge the current branch into the pre-release branch on a weekly basis.

For the following steps, treat v1.0 as the current release and v1.1 as the upcoming release.

Open Visual Studio Code to the Dapr docs repo.
From your local repo, switch to the latest branch (v1.0) and synchronize changes:
```
git pull upstream v1.0
git push origin v1.0
```
Switch to the upcoming branch (v1.1) and synchronize changes:
```
git pull upstream v1.1
git push origin v1.1
```
Create a new branch based off of the upcoming release:
```
git checkout -b upmerge_MM-DD
```
Open a terminal and stage a merge from the latest release into the upmerge branch:
```
git merge --no-ff --no-commit v1.0
```
In the terminal, make sure included files look accurate. Inspect any merge conflicts in VS Code. Remove configuration changes or version information that does not need to be merged.
Commit the staged changes and push to the upmerge branch (upmerge_MM-DD).
Open a PR from the upmerge branch to the upcoming release branch (v1.1).
Review the PR and double check that no unintended changes were pushed to the upmerge branch.

Release process

Dapr docs must align with features and updates included in the Dapr project release. Leading up to the Dapr release date, make sure:

All new features or updates have been sufficiently documented and reviewed.
Docs PRs for the upcoming release point to the release branch.

For the following steps, treat v1.0 as the latest release and v1.1 as the upcoming release.

The release process for docs requires the following:

An upmerge of the latest release into the upcoming release branch
An update to the latest and upcoming release Hugo configuration files
A new Azure Static Web App for the next version
A new DNS entry for the next version’s website
A new git branch for the next version

Upmerge

First, perform a docs upmerge from the latest release to the upcoming release branch.

Update Hugo Configuration

After upmerge, prepare the docs branches for the release. In two separate PRs, you need to:

Archive the latest release.
Bring the preview/release branch as the current, live version of the docs.
Create a new preview branch.

Latest release

These steps will prepare the latest release branch for archival.

Open VS Code to the Dapr docs repo.
Switch to the latest branch (v1.0) and synchronize changes:
```
git pull upstream v1.0
git push origin v1.0
```
Create a new branch based off of the latest release:
```
git checkout -b release_v1.0
```
In VS Code, navigate to /daprdocs/config.toml.

Add the following TOML to the # Versioning section (around line 154):

version_menu = "v1.0"
version = "v1.0"
archived_version = true
url_latest_version = "https://docs.dapr.io"

[[params.versions]]
  version = "v1.2 (preview)"
  url = "v1-2.docs.dapr.io"
[[params.versions]]
  version = "v1.1 (latest)"
  url = "#"
[[params.versions]]
  version = "v1.0"
  url = "https://v1-0.docs.dapr.io"

Delete .github/workflows/website-root.yml.
Commit the staged changes and push to your branch (release_v1.0).
Open a PR from release_v1.0 to v1.0.
Have a docs maintainer or approver review. Wait to merge the PR until release.

Upcoming release

These steps will prepare the upcoming release branch for promotion to latest release.

Open VS Code to the Dapr docs repo.
Switch to the upcoming release branch (v1.1) and synchronize changes:
```
git pull upstream v1.1
git push origin v1.1
```
Create a new branch based off of the upcoming release:
```
git checkout -b release_v1.1
```
In VS Code, navigate to /daprdocs/config.toml.
Update line 1 to baseURL - https://docs.dapr.io/.

Update the # Versioning section (around line 154) to display the correct versions and tags:

# Versioning
version_menu = "v1.1 (latest)"
version = "v1.1"
archived_version = false
url_latest_version = "https://docs.dapr.io"

[[params.versions]]
  version = "v1.2 (preview)"
  url = "v1-2.docs.dapr.io"
[[params.versions]]
  version = "v1.1 (latest)"
  url = "#"
[[params.versions]]
  version = "v1.0"
  url = "https://v1-0.docs.dapr.io"

Navigate to .github/workflows/website-root.yml.

Update the branches which trigger the workflow:

name: Azure Static Web App Root

on:
  push:
    branches:
      - v1.1
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - v1.1

Navigate to /README.md.
Update the versions table:

| Branch                                                       | Website                    | Description                                                                                      |
| ------------------------------------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------ |
| [v1.1](https://github.com/dapr/docs) (primary)               | https://docs.dapr.io       | Latest Dapr release documentation. Typo fixes, clarifications, and most documentation goes here. |
| [v1.2](https://github.com/dapr/docs/tree/v1.2) (pre-release) | https://v1-2.docs.dapr.io/ | Pre-release documentation. Doc updates that are only applicable to v1.2+ go here.                |

Update the dapr-latest-version.html shortcode partial to the new minor/patch version (in this example, 1.1.0 and 1.1).
Commit the staged changes and push to your branch (release_v1.1).
Open a PR from release/v1.1 to v1.1.
Have a docs maintainer or approver review. Wait to merge the PR until release.

Future preview branch

Create preview branch

In GitHub UI, select the branch drop-down menu and select View all branches.
Click New branch.
In New branch name, enter the preview branch version number. In this example, it would be v1.2.
Select v1.1 as the source.
Click Create new branch.

Configure preview branch

In a terminal window, navigate to the docs repo.
Switch to the upcoming release branch (v1.1) and synchronize changes:
```
git pull upstream v1.1
git push origin v1.1
```
Create a new branch based on v1.1 and name it v1.2:

git checkout -b release_v1.1

Rename .github/workflows/website-v1-1.yml to .github/workflows/website-v1-2.yml.

Open .github/workflows/website-v1-2.yml in VS Code and update the name, trigger, and deployment target to 1.2:

name: Azure Static Web App v1.2

on:
  push:
    branches:
      - v1.2
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - v1.2

 ...

     with:
       azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
       repo_token: ${{ secrets.GITHUB_TOKEN }}

 ...

     with:
       azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_V1_2 }}
       skip_deploy_on_missing_secrets: true

Navigate to daprdocs/config.toml and update the baseURL to point to the new preview website:
```
baseURL = "https://v1-2.docs.dapr.io"
```

Update the # GitHub Information and # Versioning sections (around line 148) to display the correct versions and tags:

# GitHub Information
github_repo = "https://github.com/dapr/docs"
github_project_repo = "https://github.com/dapr/dapr"
github_subdir = "daprdocs"
github_branch = "v1.2"

# Versioning
version_menu = "v1.2 (preview)"
version = "v1.2"
archived_version = false
url_latest_version = "https://docs.dapr.io"

[[params.versions]]
  version = "v1.2 (preview)"
  url = "#"
[[params.versions]]
  version = "v1.1 (latest)"
  url = "https://docs.dapr.io"
[[params.versions]]
  version = "v1.0"
  url = "https://v1-0.docs.dapr.io"

Commit the staged changes and push to a new PR against the v1.2 branch.
Hold on merging the PR until after release and the other v1.0 and v1.1 PRs have been merged.

Create new website for future release

Next, create a new website for the future Dapr release. To do this, you’ll need to:

Deploy an Azure Static Web App.
Configure DNS via request from CNCF.

Prerequisites

Docs maintainer status in the dapr/docs repo.
Access to the active Dapr Azure Subscription with Contributor or Owner access to create resources.
Azure Developer CLI installed on your machine.
Your own fork of the dapr/docs repo cloned to your machine.

Deploy Azure Static Web App

Deploy a new Azure Static Web App for the future Dapr release. For this example, we use v1.1 as the future release.

In a terminal window, navigate to the iac/swa folder in the dapr/docs directory.
```
cd .github/iac/swa
```
Log into Azure Developer CLI (azd) using the Dapr Azure subscription.
```
azd login
```
In the browser prompt, verify you’re logging in as Dapr and complete the login.

In a new terminal, replace the following values with the website values you prefer.

export AZURE_RESOURCE_GROUP=rg-dapr-docs-test
export IDENTITY_RESOURCE_GROUP=rg-my-identities
export AZURE_STATICWEBSITE_NAME=daprdocs-latest

Create a new azd environment.
```
azd env new
```
When prompted, enter a new environment name. For this example, you’d name the environment something like: dapr-docs-v1-1.
Once the environment is created, deploy the Dapr docs SWA into the new environment using the following command:
```
azd up
```
When prompted, select an Azure subscription and location. Match these to the Dapr Azure subscription.

Configure the SWA in the Azure portal

Head over to the Dapr subscription in the Azure portal and verify that your new Dapr docs site has been deployed.

Optionally, grant the correct minimal permissions for inbound publishing and outbound access to dependencies using the Static Web App > Access control (IAM) blade in the portal.

Configure DNS

In the Azure portal, from the new SWA you just created, naviage to Custom domains from the left side menu.
Copy the “CNAME” value of the web app.
Using your own account, submit a CNCF ticket to create a new domain name mapped to the CNAME value you copied. For this example, to create a new domain for Dapr v1.1, you’d request to map to v1-1.docs.dapr.io.
Request resolution may take some time.
Once the new domain has been confirmed, return to the static web app in the portal.
Navigate to the Custom domains blade and select + Add.
Select Custom domain on other DNS.
Enter v1-1.docs.dapr.io under Domain name. Click Next.
Keep Hostname record type as CNAME, and copy the value of Value.
Click Add.
Navigate to https://v1-1.docs.dapr.io and verify a blank website loads correctly.

You can repeat these steps for any preview versions.

On the new Dapr release date

Wait for all code/containers/Helm charts to be published.
Merge the PR from release_v1.0 to v1.0. Delete the release/v1.0 branch.
Merge the PR from release_v1.1 to v1.1. Delete the release/v1.1 branch.
Merge the PR from release_v1.2 to v1.2. Delete the release/v1.2 branch.

Congrats on the new docs release! 🚀 🎉 🎈

Pull in SDK doc updates

SDK docs live in each of the SDK repos. Changes made to the SDK docs are pushed to the relevant SDK repo. For example, to update the Go SDK docs, you push changes to the dapr/go-sdk repo. Until you pull the latest dapr/go-sdk commit into the dapr/docs current version branch, your Go SDK docs updates won’t be reflected on the Dapr docs site.

To bring updates to the SDK docs live to the Dapr docs site, you need to perform a straightforward git pull. This example refers to the Go SDK, but applies to all SDKs.

Pull the latest upstream into your local dapr/docs version branch.
Change into the root of the dapr/docs directory.
Change into the Go SDK repo. This command takes you out of the dapr/docs context and into the dapr/go-sdk context.
```
cd sdkdocs/go
```
Switch to the main branch in dapr/go-sdk.
```
git checkout main
```
Pull the latest Go SDK commit.
```
git pull upstream main
```
Change into the dapr/docs context to commit, push, and create a PR.

Next steps

3 - Suggested Dapr docs templates

Suggested template guidance for new Dapr doc articles

3.1 - Conceptual article template

Suggested template and guidance for creating a concept article

Contributing a new conceptual or overview article

Conceptual (or overview) articles answer the questions:

Why should you care about this feature?
What problems does it help you solve?

While a component, API, or SDK spec may help readers understand how to use or work with these features, a conceptual article provides more depth and context. Link off to the spec article, but try not to simply repeat the spec.

When naming your conceptual article, make sure it is consistent with the spec in terms of names, parameters, and terminology. Make sure you update both as needed.

Note

This template is only a suggestion. Feel free to change based on your document’s purpose.

Learn more about contributing to the Dapr docs, like front-matter and shortcodes.

Template

---
type: #Required; docs
title: #Required; Brief, clear title
linkTitle: #Required; Brief title
weight: #Required; Use the correct weight based on hierarchy
description: #Required; One-sentence description of what to expect in the article
---

<!--
Remove all the comments in this template before opening a PR.
-->

<!-- 
H1: The title in the Hugo front-matter serves as the article's markdown H1. 
-->

<!-- Introductory paragraph  
Required. Brief intro that describes the concepts that the article will cover. Link off to the appropriate reference, specs, or how-to guides to provide context. -->

<!-- 
Include a diagram or image, if possible. 
-->

## <Section 1 H2>

<!-- 
Add your content here.  
-->

## <Section 2 H2>

<!-- 
Each H2 step should start with a noun/descriptive word.
-->

## <Section 3 H2>

<!--
Add your content here.
-->

<!--
Include diagrams or images throughout, where applicable.
-->

## Try out <concept>

<!-- 
If applicable, include a section with links to the related quickstart, how-to guides, or tutorials. --> 

### Quickstarts and tutorials

Want to put the Dapr <topic> API to the test? Walk through the following quickstart and tutorials to see <topic> in action:

| Quickstart/tutorial | Description |
| ------------------- | ----------- |
| [<topic> quickstart](link) | Description of the quickstart. |
| [<topic> tutorial](link) | Description of the tutorial. |

### Start using <topic> directly in your app

Want to skip the quickstarts? Not a problem. You can try out the <topic> building block directly in your application. After [Dapr is installed](link), you can begin using the <topic> API, starting with [the <topic> how-to guide](link).


-->

## Next steps

<!--
Link to related pages and examples. For example, the related API spec, related building blocks, etc.
-->

3.2 - Quickstart guide template

Suggested template and guidance for creating a quickstart guide

Contributing a new quickstart guide

Dapr quickstart guides consist of quick instructions that walk readers through a prepared quickstart, saved to the dapr/quickstarts repo. These quickstarts package an entire feature or building block in one place, making it easy for the reader to experience how it works without compromising their own project.

The quickstart instructions should be succinct, direct, and clear. The sole purpose of a quickstart guide is to simply instruct a reader through the prepared quickstart. If you’d like to explain the concepts behind the quickstart, direct the reader to a concept article for more context.

Note

This template is only a suggestion. Feel free to change based on your document’s purpose.

Learn more about contributing to the Dapr docs, like front-matter and shortcodes.

Template

---
type: #Required; docs
title: #Required; "Quickstart: Brief, clear title"
linkTitle: #Required; This will display in the docs table of contents
weight: #Required; Use the correct weight based on hierarchy
description: #Required; One-sentence description of what to expect in the article
---

<!--
Remove all the comments in this template before opening a PR.
-->

<!-- 
H1: The title in the Hugo front-matter serves as the article's markdown H1. 
-->

<!-- Introductory paragraph  
Required. Light intro that briefly describes what the quickstart will cover. Link off to the appropriate concept or overview docs to provide context. -->

<!-- 
Include a diagram or image, if possible. 
-->

<!-- 
Make sure the quickstart includes examples for multiple programming languages. 
-->

## Pre-requisites

<!--
Make sure the reader is prepared for a successful quickstart walk through by listing what they may need.
-->

## Step 1: Set up the environment

<!-- 
Link to the quickstart sample for the reader to clone. 
-->

## Step 2: <action or task>

<!-- 
Each H2 step should start with a verb/action word.
-->

<!--
Include code snippets where possible. 
-->

## Tell us what you think!

We're continuously working to improve our Quickstart examples and value your feedback. Did you find this quickstart helpful? Do you have suggestions for improvement?

Join the discussion in our [discord channel](https://discord.gg/22ZtJrNe).

<!-- Since Dapr is an open community of contributors, make sure to provide a link to the discord discussion to welcome feedback.
-->

## Next steps

<!--
Link to related pages and examples. For example, the building block overview, the HTTP version of an SDK quickstart sample, etc.
-->

<!--
Use the button shortcode to direct readers to more in-depth, related scenarios, like the Dapr tutorials.
-->

3.3 - How-to guide template

Suggested template and guidance for creating a how-to guide

Contributing a new how-to guide

How-to guides provide step-by-step practical guidance to readers who wish to:

Enable a feature
Integrate a technology
Use Dapr in a specific scenario

How-to guides can be considered “next-level”, self-guided docs compared to quickstarts. How-to scenarios will take longer and can be more easily applied to the reader’s individual project or environment.

When naming your how-to document, include the sub-directory name in the file name. If you need to create a new sub-directory, make sure it’s descriptive and includes the relevant component or concept name. For example, pubsub-namespaces.

Note

This template is only a suggestion. Feel free to change based on your document’s purpose.

Learn more about contributing to the Dapr docs, like front-matter and shortcodes.

Template

---
type: #Required; docs
title: #Required; "How to: Brief, clear title"
linkTitle: #Required; "How to: Shorter than regular title, to show in table of contents"
weight: #Required; Use the correct weight based on hierarchy
description: #Required; One-sentence description of what to expect in the article
---

<!--
Remove all the comments in this template before opening a PR.
-->

<!-- 
H1: The title in the Hugo front-matter serves as the article's markdown H1. 
-->

<!-- Introductory paragraph  
Required. Light intro that briefly describes what the how-to will cover and any default Dapr characteristics. Link off to the appropriate concept or overview docs to provide context. -->

<!-- 
Include a diagram or image, if possible. 
-->

<!--
If applicable, link to the related quickstart in a shortcode note or alert with text like:

 If you haven't already, [try out the <topic> quickstart](link) for a quick walk-through on how to use <topic>.

-->

<!-- 
Make sure the how-to includes examples for multiple programming languages, OS, or deployment targets, if applicable. 
-->

## <Action or task>

<!-- 
Unlike quickstarts, do not use "Step 1", "Step 2", etc.  
-->

## <Action or task>

<!-- 
Each H2 step should start with a verb/action word.
-->

<!--
Include code snippets where possible. 
-->

## Next steps

<!--
Link to related pages and examples. For example, the building block overview, the related tutorial, API reference, etc.
-->