| Version 5 (modified by , 15 years ago) ( diff ) |
|---|
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.
I think it's also worth to "collect" the existing recipes and resources on the Web, point to good ones, maybe provide some additional context for them. It would be bad to duplicate existing recipes. — cboos
"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, where 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.
The wiki:CookBook/<topic> page itself can be used as an index.
It can contain links to sub-topics or the recipes themselves.
If the index grows too big, sub-topics can be created.
Also, links to external recipes could be referenced from the index page,
and notes and appreciation for the recipe could be written there.
E.g. the following recipe:
http://how-to-solutions.com/how-to-install-trac-on-windows.html
could be referenced in CookBook/Installation, and discussed there. If later on, we have too many recipes referenced, sub-topics (like CookBook/Installation/Windows) could be created.
Some suggestions for broad topics are:
— cboos
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…!
Suggestions for the next steps:
- there was also a TracCookbook/ page, I think CookBook/ alone is simply easier to use (e.g. is it TracCookbook or TracCookBook?). I'll update the TracCookbook/About page to redirect here.
- 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. Those should be linked from the CookBook/Installation page.
— cboos
