Problem
You want to add a new recipe or topic to the WebCatCookbook.
Solution
Create a new recipe.
A recipe consists of six main sections:
- The problem definition concisely presents the problem
- The solution presents the preferred solution
- The discussion discusses tradeoffs inherent in the solution and other possible solutions
- See Also references other related recipes
- Contributors lists the signatures of recipe's author(s)/contributor(s)
- Comments includes wide-ranging discussions about the recipe contributed by readers. Often, comments are about are material that isn't directly relevant to the solution(s) in the recipe. They may discuss meta issues.
Creating a new recipe involves four main steps:
Create a new recipe page using the form below, and give it a meaningful WikiName. The form below is provided for convenience--you can actually use any mechanism you want to create a new page (see HelpOnPageCreation), and then select the RecipeTemplate as part of the page creation process.
Edit the contents of your new recipe. The RecipeTemplate includes placeholders for the standard sections in a recipe. However, don't feel overly constrained by this template; it is merely a guideline. Feel free to add new sections or subsections to make your recipe clear, or to delete or rename existing sections if they do not apply to your topic.
At the bottom of the page (if you are using the RecipeTemplate), you'll see a laundry list of possible categories that may apply to your new recipe. Delete the category names that don't apply to your new recipe. Most recipes are listed in three categories: CategoryRecipe, CategoryCookbook, and a category named after the corresponding chapter of the cookbook in which the recipe belongs.
Finally, be sure to save your new page and then edit the WebCatCookbook table of contents. Add an entry for your new page to the appropriate chapter.
OK, so now that you've read all this, you are ready to create a new recipe:
Discussion
There are two main reasons for creating recipes:
You have a problem you would like help with. Make sure you specify at least the problem statement in the recipe and be sure to place it in CategoryRecipeStub by leaving this category name in the category list at the bottom of your page when you save it. If you create a recipe for this reason you should try to make the problem as general as possible so other people can benefit from it. If you make the problem very specific don't be surprised if the problem statement is changed.
- You have knowledge you wish to share. In this case you'll probably fill in at least the problem and solution, and perhaps the discussion as well.
If there are two or more very different solutions, and neither is superior in the general case, document them both (using subsections to make things readable). Ideally, you would want to include an appropriate discussion of when one of the alternatives is preferable, so that readers will have some basis for choosing. Usually, the solutions would be placed in the solution section, while rationale and other clarification information would appear in the Discussion section.
In all cases, of course, the goal is to be clear and readable, rather than to slavishly adhere to a specific format for recipes.
See Also
The Author Guide in the WebCatCookbook
Contributors
-- StephenEdwards 2006-03-24 04:22:06
Comments