Trac Cookbook

Introduction

My experiences installing and configuring a Trac site, as well as following threads in the Trac Users Group have convinced me of the need for a "cookbook" for Trac containing "recipes" for accomplishing particular tasks. By a "recipe" I mean a clear and reliable set of instructions that have a very high probability of working under a broad range of conditions. The recipe should also be complete and self-contained in the sense that one should be able to start at the beginning and end up with the desired goal at the end of the steps — no prerequisites, and no unexplained steps. Ideally, the "why" for the steps will also be included.

Recipes

Loads of information on how to accomplish particular tasks with Trac already exists in one form or another in forum posts, blogs, third party web pages, and even the Trac documentation. However, this non-centralized information can sometimes be hard to find, especially if the "answer" is buried somewhere in the middle of a forum thread. Often the prerequisites for the answer — conceptual, hardware, or software — are often missing. Most importantly, there is generally no guarantee that the solution wil work.

Ideally, a "recipe" will be a more or less complete how-to, from beginning to end. A recipe would be a complete description such that if a person starts at step 1 and takes every step until the end, the goal will be reached and work for the specified version of Trac. No foreknowledge or pre-requisite settings required.

Sources for Recipes

Ideally, the cookbook will be open to both suggestions for recipes and the recipes themselves. In order for the cookbook to work, there will need to be some way to moderate or grade the solution so the users can be reasonably sure that the recipes wil work, and at worst not break their Trac.

"Writing" the Cookbook

There is an ongoing discussion right now in the trac users group on how best to pull in and organize the cookbook content, what to call the cookbook, were it will live, and how it will relate to the Trac "documentation" (in the traditional sense). More will be posted here soon as these ideas gel.

What next?

I created this page with the following idea in mind: The cookbook could initially live here under wiki:CookBook/<topic>/<sub_topic>/<etc.>. If I can get to where I'm not writing this any more, I might try writing some recipes to get things started.

Can I submit a recipe?

Good question. I'm not sure how best to do this yet. If you just make a page, will we be sure the recipe works. I don't want to start flooding trac.edgewall.org with tickets for the cookbook. Hmmmm…. Not sure yet.

Please stay tuned for more…!