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

Return to the regular view of this page.

Suggested Dapr docs templates

Suggested template guidance for new Dapr doc articles

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.

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

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.

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

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