Edgewall Software

Version 4 (modified by Christian Boos, 15 years ago) ( diff )

a few suggestions

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 recipes should also be complete and self-contained.

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.

A good "recipe" will be a more or less complete how-to 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 undisclosed prerequisites, and no unexplained steps. Ideally, the "why" for the steps will also be included.

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…!

(cboos) A few suggestions for the next steps:

  • make it clear which of CookBook/ or TracCookbook/ is the right hierarchy to use. Currently this page (CookBook/About) shares the same content with TracCookbook/About, and it's not clear which one you really intend to use (one should redirect to the other, at the very least)
  • there are already quite a lot of such recipes here in the Wiki, e.g. TracNginxRecipe, PostgresqlRecipe, the various platform install guides have also most of the time a recipe-like structure as described above
  • you could gather already existing recipes in sub-pages (say of CookBook/), merely linking to existing recipes for start and devise some kind of "status box" for them (submitted as of ../../.., verified by xyz ../../.. + comments)
Note: See TracWiki for help on using the wiki.