Describe recipes and differentiate from user guides (#118)
* Describe recipes and differentiate from user guides
* Update CONTRIBUTING.md
Co-authored-by: Nic Crane <thisisnic@gmail.com>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e87e6ec..97e7ed1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,6 +4,19 @@
If you find a bug in the cookbook, please let us know by opening an issue on GitHub.
+## What makes a good recipe?
+
+Recipes are solutions to specific problems that the user can copy/paste into their own code.
+They answer specific questions that users might search for on Google or StackOverflow.
+Some questions might be trivial, like how to read a CSV, while others might be more
+advanced; the complexity doesn't matter. If there is someone searching for that question,
+the cookbook should have an answer for it.
+
+Recipes should provide immediate instructions for how to perform a task, including a
+code example that can be copied and pasted. They do not need to explain the theoretical
+knowledge behind the solution, but can instead link the relevant part of the Arrow user
+guide and API documentation.
+
## Do you want to contribute new recipes or improvements?
We always welcome contributions of new recipes for the cookbook.
diff --git a/README.rst b/README.rst
index fb6928e..a71f032 100644
--- a/README.rst
+++ b/README.rst
@@ -6,6 +6,13 @@
composed of multiple cookbooks, one for each supported platform,
which contain the recipes for that specific platform.
+The cookbook aims to provide immediate instructions for common tasks, in
+contrast with the [Arrow User Guides](https://arrow.apache.org/docs/index.html)
+which provides in-depth explanation. In terms of the
+[Diátaxis framework|https://diataxis.fr/], the cookbook is *task-oriented*
+while the user guide is *learning-oriented*. The cookbook will often refer to
+the user guide for deeper explanation.
+
All cookbooks are buildable to HTML and verifiable by running
a set of tests that confirm that the recipes are still working
as expected.
