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

  1. ---
  2. type: #Required; docs
  3. title: #Required; "How to: Brief, clear title"
  4. linkTitle: #Required; "How to: Shorter than regular title, to show in table of contents"
  5. weight: #Required; Use the correct weight based on hierarchy
  6. description: #Required; One-sentence description of what to expect in the article
  7. ---
  8. <!--
  9. Remove all the comments in this template before opening a PR.
  10. -->
  11. <!--
  12. H1: The title in the Hugo front-matter serves as the article's markdown H1.
  13. -->
  14. <!-- Introductory paragraph
  15. 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. -->
  16. <!--
  17. Include a diagram or image, if possible.
  18. -->
  19. <!--
  20. If applicable, link to the related quickstart in a shortcode note or alert with text like:
  21. If you haven't already, [try out the <topic> quickstart](link) for a quick walk-through on how to use <topic>.
  22. -->
  23. <!--
  24. Make sure the how-to includes examples for multiple programming languages, OS, or deployment targets, if applicable.
  25. -->
  26. ## <Action or task>
  27. <!--
  28. Unlike quickstarts, do not use "Step 1", "Step 2", etc.
  29. -->
  30. ## <Action or task>
  31. <!--
  32. Each H2 step should start with a verb/action word.
  33. -->
  34. <!--
  35. Include code snippets where possible.
  36. -->
  37. ## Next steps
  38. <!--
  39. Link to related pages and examples. For example, the building block overview, the related tutorial, API reference, etc.
  40. -->

Last modified October 11, 2024: Fixed typo (#4389) (fe17926)