I thought I'd direct my reply here, since this seems to be where TG docs discussion should happen these days. I hope nobody minds.
On Feb 12, 3:41 am, "Jorge Vargas" <[EMAIL PROTECTED]> wrote: > On 2/8/07,BenSizer<[EMAIL PROTECTED]> wrote: > > The main docs that Turbogears lack are generally the absolute basic, > > minimum ones that most projects consider the bare essentials: a > > reference to what everything does. Fixing that is not a job for users, > > it's a job for the developers. Once the developers have done what > > should have been done long ago, only then can the typical user of the > > framework be expected to have a decent enough understanding of what is > > going on to be able to contribute anything of significant worth. > > Certainly nobody with a stake in this project has a right to start > > demanding docs from people when they haven't even bothered to explain > > the basics. > > please by all means be concrete the core basics are documented what is > not documented are the addons there is even a set of diagrams with the > flow of requests. I disagree. At the time when I posted the above, there still was no API reference, which is the crucial base point for documentation. Tutorials and walkthroughs just do not cut it. Few people want to read through someone else's arbitrary use case in order to determine which parameters you can pass to a function. Even including that new API reference, there are several things still lacking. eg. The validate decorator is very important and has virtually no reference documentation. Similarly, the controller reference doesn't explain how to arrange a hierarchy of controllers and methods to map to URLs, or cover the whole default/index system. You have to dig through one of the walkthroughs or tutorials for that. I'd say these are core basics. I also have no idea where the set of diagrams are that you speak of. They certainly don't seem to have a prominent link from the docs page. As a slight aside, I think that API docs as a definitive guide to the core operations are doomed to failure as long as the approach is to auto-generate them. One reason is that pulling comments from the code severely limits the number of people who can contribute directly to the docs. Another is that extensive inline docs clutter up the code itself. And Python is a poor language for such a system anyway. Docstrings stay resident during execution, meaning better docs leads to more resource usage. Functions can be called on the assumption that they may or may not even exist; how do you automatically document the semantics of a 'default' method on a controller when no such method even exists in the base controller class? How do you talk about the expected parameters to a function when actually that function takes **kwargs and forwards them to a private function which is not exposed to the docs? I think most of the core Turbogears functionality (the decorators, controllers, widgets, validators) needs hand-written documentation, made consistent by using a common template as you might see in MSDN or man pages. -- Ben Sizer --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "TurboGears Docs" 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-docs?hl=en -~----------~----~----~----~------~----~------~--~---
