Introduction

WORK IN PROGRESS

This cookbook is still in its very early stages. At this point, we will not be linking to it from anywhere else. Pages may be removed or reorganized at any time. Even the goals and overall format are still in flux.

The Cookbook vs the Guide

How is the cookbook different from the guide? Why is this necessary?

Guidelines for Recipes

Recipes should generally:

  1. Solve a specific, common problem

  2. Start with the simplest possible example

  3. Introduce complexities one at a time

  4. Link to other docs, rather than re-explaining concepts

  5. Describe the problem, rather than assuming familiarity

  6. Explain the process, rather than just the end result

  7. Explain the pros and cons of your strategy, including when it is and isn’t appropriate

  8. Mention alternative solutions, if relevant, but leave in-depth explorations to a separate recipe