On 2/3/07, Mark Ramm <[EMAIL PROTECTED]> wrote: > > I understand the frustration. > > Fundamentally we need more help. Documentation is a big project, and a > lot of people have worked very hard to get us where we are. There's still > some way to go, I don't think we're miles away from good enough. The > largest missing pieces are the API docs, a good overview, and some > additional widget documentaiton, so the end is really in sight. > > We ran into snags with API documentation generation in the last sprint, > and as far as I know there hasn't been any movement on that since.
actually see my post on the docs list, I'm waiting for Lee to have some time to try it out on TG server. IMO epydoc is good enough for this. If somebody has time to work out the kinks we've experienced with epydoc > that would be great. that is some weirdness with widgets which I spend most of the last docsprint researching and couldn't find any logical reason, other then some python-foo inside widgets that was too much for epydoc. If somebody is willing to try to get pudge, or another doc generation tool > working that would also be great. I'll see if I can work something around it because now it seems to be maintained again. But I'm hoping that somebody will volunteer to help out with it again at our > next docsprint and we can actually move this piece across the finish line, > and get API docs linked up to docs.turbogears.org. > > What I'd really love is for a couple of people to work with different API > generation tools, so if we run into snags with one tool or another we still > have a good chance of actually getting something completed. > > --Mark Ramm > > On 2/3/07, Steve Bergman <[EMAIL PROTECTED]> wrote: > > > > > > I've been following TG for about 16 months. I've noted an ongoing > > background lament about how "we should have more complete docs". And > > while things may have gotten better, the documentation is still a > > disgrace compared to other frameworks like Rails. (And Rails is > > sometimes criticized for insufficient docs.) > > > > Documentation sprints have come and gone, complete with reports from > > the battlefront about how amazingly well things were going and how > > much progress was being made. > > > > But after the sprints... nothing. > > > > The last sprint was no exception. > > > > I'm looking at docs.turbogears.org/1.0 for docs. Am I simply > > mistaken? Should I be looking somewhere else for official docs? > > > > Still no proper widget documentation. Still no proper API reference. > > And yet I distinctly remember a report from the last sprint that great > > progress was being made in that area. > > > > I've heard it said that the book documents TurboGears 1.0. It does > > not. It is not a reference. And compared to more in depth books like > > "Agile Programming With Rails", is really just an overview. > > > > Frankly, TG needs decent 1.0 reference documentation a *lot* more than > > it needs a 2.0. > > > > 1.0 was not supposed to be allowed out without complete docs... or so > > I remember hearing many times. > > > > And if it takes closing all TG branches on Trac to all tickets that > > are not documentation bug fixes than so be it. > > > > I apologize for the negative tone. > > > > And I really *do* appreciate all the hard work that has gone into > > writing the actual TG code. > > > > And I apologize if I have just screwed up and am not looking in the > > right place. (But please don't point me to yet another collection of > > little user-provided use case snippets on some wiki.) > > > > After 17 months, it is not at all unreasonable for users to expect > > real docs, and (silently) to move on to something else if they don't > > exist. > > > > > > > > > -- > Mark Ramm-Christensen > email: mark at compoundthinking dot com > blog: www.compoundthinking.com/blog > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears" 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/turbogears?hl=en -~----------~----~----~----~------~----~------~--~---
