hear here - being dying to say this since I started with TG - thought I was just missing it, or stupid for needing it or something On Sun, 2006-09-03 at 12:49 -0700, Ben Sizer wrote: > I didn't see this mentioned anywhere else, so I thought I'd bring it > up. > > A lot of effort seems to be getting put into the tutorials, and into > the various 'how to do X' mini tutorials. The Getting Started guide is > really just yet another tutorial. But one major thing seems to be > forgotten; the API reference is woefully lacking, and I don't hear > about anybody attempting to fix it. It's not surprising that it's been > relegated to the bottom of the list. Talk of migrating docs to a wiki > seems to emphasise that this has flown beneath the radar. I know we > live in an age of screencasts and so on, but that doesn't change the > fact that the average programmer probably uses reference material far > more than they'll use tutorials. Yet we're apparently neglecting that > reference material. > > If you look at the API Reference page, you get a screen which is pretty > useless - a list of subpackages and modules, many of which seem to be > for internal use, none of which have any sort of description. Worse > still, all you get is this top-down view; there's no index for a > bottom-up search, which is probably what most users are going to want. > > If you click on a module, eg. controllers, you get shown a lot of > private functions which shouldn't really be in the docs, and a lot of > poorly documented functions. expose() is reasonably well documented, > although even that has one big problem, which is pretty much witnessed > throughout - there are no examples. Even if you've got this far, and > seen which parameters you can pass in, working out what types are > expected is often a case of guesswork. > > So, let me summarise... the main problems in my humble opinion are: > > - No 'table of contents' that is organised in a usable manner > - No index > - No or very few usage examples > - Private functions need removing > > In theory, this shouldn't be that big a problem to fix: Turbogears > seems to actually have very few public classes and methods which the > end user needs to know about. They just need detailing in an exhaustive > way, rather than spreading information about their capabilities > throughout 3 or 4 different tutorials. > > I really think that the MSDN docs are a 1st class example to follow > here. Each function has its own page, stating which module or object > it's from, what parameters it takes and what type they are, what it > returns, any remarks on how the function operates, and an example of > how the function would typically be used in context. I appreciate that > all that might be a little much for a Python docstring, but that just > emphasises the limitations of auto-generated docs really. > > Comments welcome. >
--~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
