Problem

You would like to describe a feature/use-case/behavior/workflow on the platform, but you are not sure how to document it.

Solution

  1. Create a new article, based on the following cookbook-style recipe template.

  2. Add your article to the correct collection.

  3. Publish your article.

  4. Consider updating other articles that should link to this article.

Discussion

Cookbooks-style recipe are inspired by O'Reilly Cookbooks, and are meant to:

  • Be clear about the audience

  • Be clear and focused about the problem

  • Offer a quick and easy solution

  • Provide an additional explanation of the solution to those that are curious

  • Link to other related problems

Every cookbook-style recipe, or a guide, should use the following format:

  • Title - A short, high-level, search-friendly description of what your recipe is about.

  • Tag - An optional extended description of your recipe, letting you include additional keywords your audience will search for.

  • Problem - Identifies the audience and the problem they are looking to solve. This anchors the rest of the recipe. Moreover, this helps the reader quickly determine if the article maps well to their issue.

  • Solution - Provides a quick answer to the problem, without an extended explanation or a justification. Should be easy to follow and copy-paste friendly.

  • Discussion - Provides a deeper explanation of the problem and the solution, including any options and alternatives. This can help readers better understand, and therefore trust the solution.

  • See Also - An optional list of links to related articles or external resources. Note, it's encouraged to liberally link to other recipes in other sections of a recipe. Having a dedicated See Also section may seem redundant, but it helps the reader trust that they can quickly navigate across related content and not worry about bookmarking each article.

To make articles that are easy to consume, compose, and maintain check out Help Center Best Practices.

See Also

Did this answer your question?