Skip to content
Permalink
Browse files
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>
  • Loading branch information
wjones127 and thisisnic committed Jan 16, 2022
1 parent 350c6e0 commit 9ba5f601ea948c653a0278374e185975706fcff4
Showing 2 changed files with 20 additions and 0 deletions.
@@ -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.
@@ -6,6 +6,13 @@ that Arrow users might want to do. The cookbook is actually
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.

0 comments on commit 9ba5f60

Please sign in to comment.