Recipe

A recipe answers a very specific problem and provides a solution to resolve it. For example, ActiveState provides a huge repository of Python recipes online, where developers can describe how to do something in Python (refer to http://code.activestate.com/recipes/langs/python/). Such a set of recipes related to a single area/project is often called a cookbook.

These recipes must be short and are structured, like this:

• Title
• Submitter
• Last updated
• Version
• Category
• Description
• Source (the source code)
• Discussion (the text explaining the code)
• Comments (from the web)

Often, they are one screen long and do not go into great detail. This structure perfectly fits a software's needs and can be adapted in a generic structure, where the target readership is added and the category is replaced by tags:

• Title (short sentence)
• Author
• Tags (keywords)
• Who should read this?
• Prerequisites (other documents to read, for example)
• Problem (a short description)
• Solution (the main text, one or two screens)
• References (links to other documents)

The date and version are not useful here, since project documentation should be managed like source code in the project. This means that the best way to handle the documentation is to manage it through the version control system. In most cases, this is exactly the same code repository as the one that's used for the project's code.

A simple reusable template for the recipes could be as follows:

=========== 
Recipe name 
=========== 
 
:Author: Recipe Author 
:Tags: document tags separated with spaces 
 
:abstract: 
 
    Write here a small abstract about your design document. 
 
.. contents :: 
 
 
Audience 
======== 
 
Explain here who is the target readership. 
 
 
Prerequisites 
============= 
 
Write the list of prerequisites for implementing this recipe. This can be additional documents, software, specific libraries, environment settings or just anything that is required beyond the obvious language interpreter. 
 
 
Problem 
======= 
 
Explain the problem that this recipe is trying to solve. 
 
 
Solution 
======== 
 
Give solution to problem explained earlier. This is the core of a recipe. 
 
 
References 
========== 
 
Put here references, and links to other documents.