The dozen of you (you being the 1,225 people subscribed to this group) that have signed up for tg-tickets may have noticed that I fixed it this morning, and we've gotten a nice steady stream of ticket updates since then.
eleddy (hi!) submitted this timely ticket. I say timely, because I've been thinking about docs quite a bit lately (not surprising given the big, impending release). Barring major showstoppers, I'm planning to use Fredrik Lundh's PythonDoc for API documentation. But, that's not the kind of docs that most people *need* when they're getting up to speed and working on new things. Currently, TurboGears primary documentation is in svn as XHTML files (Kid templates, really). There are pluses to this arrangement: the docs automatically follow the software, there's no question about how it translates for the web, you can use all web features (like JavaScript syntax coloring!), and static files serve very, very fast. There's been some discussion lately on cherrypy-devel about docs, and they're planning to use a blog tool with categories, displaying all of the articles for each category as a table of contents. They'll use categories to denote the various CP versions for which a given article applies. This is not a bad arrangement (though the one thing that is really missing from this scheme, which they may end up adding when they use it, is the ability to copy an article to make changes for a new version). A wiki adds to this the ability to link easily to different articles. I wrote a bit about a wiki for software documentation here: http://www.blueskyonmars.com/2005/09/27/what-i-want-in-a-wiki-for-software-development/ I wanted to raise this for discussion and, hopefully, volunteers who'd like to work on the app. I am more than 100% booked right now, but an app like this would be really helpful. Thoughts? Kevin ---------- Forwarded message ---------- From: TurboGears <[EMAIL PROTECTED]> Date: Feb 3, 2006 12:48 PM Subject: [tg-tickets] [TurboGears] #510: Public discussion at the bottom of public documentation/tutorials To: [EMAIL PROTECTED] #510: Public discussion at the bottom of public documentation/tutorials ------------------------------+--------------------------------------------- Reporter: [EMAIL PROTECTED] | Owner: anonymous Type: enhancement | Status: new Priority: low | Milestone: Component: Docs | Version: Severity: normal | Keywords: ------------------------------+--------------------------------------------- I am just getting started with TG and noticed that there is no discussion at the bottom of the non-wiki tutorials/documentation. I think that this can be a valuable place for developers to share information, pitfalls, etc... For example, I did the 20 minute wiki tutorial, and tried to add another template in the process. While it seemed like I could copy and paste and do a little mod here and there, it took me some time to discover that a template is ONLY invoked if a dictionary is returned (which is not an intuitive behaviour). I feel like this is something that should be clarified, but there is no real place in the wiki for something like this, and looking around there for FAQ's and what not is weird anyways. php.net and plone.org are great example where other developers can put in relevant clarifications, suggestions. It also encourages the community to give back and participate in the proj, while maintaining "quality" control of docs. If this is something that you would be interested in implementing, I have no issue putting in the code. Email [EMAIL PROTECTED] Thanks! -- Ticket URL: <http://trac.turbogears.org/turbogears/ticket/510> TurboGears <http://www.turbogears.org/> TurboGears front-to-back web development -- Kevin Dangoor Author of the Zesty News RSS newsreader email: [EMAIL PROTECTED] company: http://www.BlazingThings.com blog: http://www.BlueSkyOnMars.com
