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. -- Ben Sizer --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
