new file mode 100644
--- /dev/null
+++ b/doc/recipes.txt
@@ -0,0 +1,59 @@
+.. -*- mode: rst; encoding: utf-8 -*-
+
+=============
+Build Recipes
+=============
+
+A build recipe tells a build slave how a project is to be built. It consists of
+multiple build steps, each defining a command to execute, and where artifacts
+can be found after that command has successfully completed.
+
+Build recipes are intended to supplement existing project build files (such as
+Makefiles), not to replace them. In general, a recipe will be much simpler than
+the build file itself, because it doesn't deal with all the details of the
+build. It just automates the execution of the build and lets the build slave
+locate any artifacts and metrics data generated in the course of the build.
+
+A recipe can and should split the build into multiple separate steps so that the
+build slave can provide better status reporting to the build master while the
+build is still in progress. This is important for builds that might take long to
+execute. In addition, build steps help organize the build results for a more
+structured presentation.
+
+.. contents:: Contents
+   :depth: 2
+.. sectnum::
+
+
+File Format
+===========
+
+Build recipes are stored internally in an XML-based format. Recipe documents
+have a single ``<build>`` root element with one or more ``<step>`` child
+elements. The steps are executed in the order they appear in the recipe.
+
+A ``<step>`` element will consist of any number of commands and reports. Most of
+these elements are declared in XML namespaces, where the namespace URI defines
+a collection of related commands.
+
+.. code-block:: xml
+
+  <build xmlns:python="http://bitten.cmlenz.net/tools/python">
+  
+    <step id="build" description="Compile to byte code">
+      <python:distutils command="build"/>
+    </step>
+  
+    <step id="test" description="Run unit tests">
+      <python:distutils command="unittest"/>
+      <python:unittest file="build/test-results.xml"/>
+      <python:trace summary="build/test-coverage.txt" 
+          coverdir="build/coverage" include="trac*" exclude="*.tests.*"/>
+    </step>
+  
+  </build>
+
+See `Build Recipe Commands`_ for a comprehensive reference of the commands
+available by default.
+
+.. _`build recipe commands`: commands.html