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

  1. ---
  2. type: #Required; docs
  3. title: #Required; Brief, clear title
  4. linkTitle: #Required; Brief title
  5. weight: #Required; Use the correct weight based on hierarchy
  6. description: #Required; One-sentence description of what to expect in the article
  7. ---
  9. <!--
  10. Remove all the comments in this template before opening a PR.
  11. -->
  13. <!-- 
  14. H1: The title in the Hugo front-matter serves as the article's markdown H1. 
  15. -->
  17. <!-- Introductory paragraph  
  18. 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. -->
  20. <!-- 
  21. Include a diagram or image, if possible. 
  22. -->
  24. ## <Section 1 H2>
  26. <!-- 
  27. Add your content here.  
  28. -->
  30. ## <Section 2 H2>
  32. <!-- 
  33. Each H2 step should start with a noun/descriptive word.
  34. -->
  36. ## <Section 3 H2>
  38. <!--
  39. Add your content here.
  40. -->
  42. <!--
  43. Include diagrams or images throughout, where applicable.
  44. -->
  46. ## Try out <concept>
  48. <!-- 
  49. If applicable, include a section with links to the related quickstart, how-to guides, or tutorials. --> 
  51. ### Quickstarts and tutorials
  53. Want to put the Dapr <topic> API to the test? Walk through the following quickstart and tutorials to see <topic> in action:
  55. | Quickstart/tutorial | Description |
  56. | ------------------- | ----------- |
  57. | [<topic> quickstart](link) | Description of the quickstart. |
  58. | [<topic> tutorial](link) | Description of the tutorial. |
  60. ### Start using <topic> directly in your app
  62. 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).
  65. -->
  67. ## Next steps
  69. <!--
  70. Link to related pages and examples. For example, the related API spec, related building blocks, etc.
  71. -->

Last modified September 27, 2022: Docs contributing guide updates (#2768) (73861088)