Ok. I'm starting to officially feel like my topic is being hijacked, albeit unintentionally and with the best of intentions.
I'm want to reiterate my proposal and also explain how what I mean by "recipes" differs from documentation. TRAC COOKBOOK I proposed taking on the project of compiling a "cookbook" for Trac made of "recipes" collected from around the web, forums, mailing lists, etc. based on solutions to common tasks (not necessarily solutions to ''problems''). There is a lot of information floating around in the web, especially in the middle and ends of threads, on how to achieve particular goals. Sometimes this information is hard to assemble and assimilate in a timely manner because it is non-centralized and, as I said, in pieces throughout discussions. By a "recipe" I mean a more or less complete how-to from beginning (noob) to end for how to achieve a particular goal. 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. Here are some examples that are just popping up: 1) How to set up track to use various methods of authentication. I know a lot of this is in the docs and TracInstall. However, I found that I still needed to do a lot of trial and error. This was especially true when I wanted to use the login form rather than the .htaccess apache window and have true logout. I had to turn off some features of the accounts manager and not others. 2) How to install and use ticket enhancing plugins: 3) How to create, implement and package a new theme. 4) Different ways to structure and use the wiki. 5) Different ways to use a Trac site. For example: code development, project management, task management, etc. What would a typical installation geared towards these uses include and how would it be managed. 6) How to set up Trac to use my favorite method of ticket tracking. (Not really familiar enough with ticket systems to give examples, just an idea based on threads I see go by in this group). RECIPES VS DOCUMENTATION The purpose of documentation is to provide a comprehensive description of features and how to use them. The purpose is for reference, not necessarily for usability in a given context. For many programming languages and operating systems there exist both documentation and recipe books. They have separate goals. The python docs explicitly lay out the features of the python language and how to use them. The Python Cookbook (http://oreilly.com/catalog/9780596007973/) is a collection of snippets and solutions for doing things like: "Modifying the class hierarchy of an instance", "Splitting a path into all of its parts", "Manipulating Windows Services", "Grabbing a document from the web". These recipes use ''ingredients'' from the documentation to create a delicious python ''dish'' or ''meal''. EXISTING EFFORTS There are clearly a few efforts already out there to improve the usability and completeness of documentation. I'm glad the motivation is there as I think it will really help the Trac community. I plan to contribute to this effort. I want to review the responses in this thread to see how I can best help. However, I still think a "Cookbook" is different from documentation and will be a valuable companion. I would like to hear if others agree or disagree. PROCESS Here is an off-the-cuff proposal for how this would work. I and perhaps a few others would moderate the cookbook. We would begin populating the cookbook with just whatever occurs to us or appears useful based on irc chats and threads in this group. We would also lay out some sort of hierarchical structure such as (Installation, Authentication, Tickets, Workflow, etc...). We would also use tags. We would also try to set out some principles for our chief priorities. The community would request recipes via tickets. Based on our priorities, the moderators and entire community would search around for solutions. When a solution is found, it will need to be tested and verified sufficiently. When the moderators agree that the solution works, we will commit it to the cookbook. As requests come in, we can update our priorities. HOSTING I'm still looking for suggestions for where this thing could be hosted. If all else fails, I can start it on my own server. I'd rather it be public/donated space. Thanks again, Ariel Remy Blank wrote: > Noah Kantrowitz wrote: > >> Converting Trac wiki markup to ReST is more annoying than it sounds ;-) >> > > I bet it is. And automatic conversion is probably out of the question, > too. Still, better than having no content at all? > > >> Definitely doable but be careful or you will be right back at wiki doc-rot. >> > > You mean this effort should be better coordinated? You are probably > right. I would suggest that contributors "take ownership" of the pages > they add, as opposed to the "anonymous" TracGuide pages, by indicating > their author status at the top of the page. This should clearly show > that they take responsibility for the quality of the content, and > moderate any changes done by third parties. > > -- Remy > > -- /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\ Ariel I Balter, Ph.D. Postdoc Biological Monitoring/Modeling Fundamental and Computational Sciences Directorate Pacific Northwest National Laboratory Mail: PO Box 999, MS P7-58,Richland, WA 99352 Shipping: 790 6th Street, MS P7-58, Richland, WA 99354 Tel: 509-376-7605 Cell: 509-713-0087 [email protected] www.arielbalter.com www.pnl.gov --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Users" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/trac-users?hl=en -~----------~----~----~----~------~----~------~--~---
begin:vcard fn:Ariel Balter, PhD n:Balter;Ariel email;internet:[email protected] tel;home:812-332-2721 tel;cell:812-219-4558 x-mozilla-html:TRUE url:http://arielbalter.com version:2.1 end:vcard
