On 2/5/07, Steve Bergman <[EMAIL PROTECTED]> wrote: > > > > > On Feb 4, 6:52 pm, "Mark Ramm" <[EMAIL PROTECTED]> wrote: > > I'd like to hear the specifics of what you think needs attention in > > the TurboGears Documentation. > > > > >From my perspective as one who develops in TG but do not develop TG > itself: > > I think that *quality* reference docs on the API is going to be a tall > enough order all by itself, and will keep people busy for a long > time. I'm not certain, but I suspect that once the API docs are > autogenerated they are going to be lacking. Documentation written > long after the fact has a tendency to be that way. In particular, I > would emphasize widgets themselves, and the widget framework.
yes indeed but having this being posted somewhere is an insentive to write docstrings, maybe not for the person writting the code but it's a simplier place for "users" to help out on documentation, since writting formal docs and tutorials is harder then understanding a couple of methods. People don't so much mind hunting around a bit for full example > documents about using the . But if the reference API documentation is > missing, incomplete, erroneous, or indecipherable, it really makes > things hard and undermines the users' confidence in the project. yes IMO this is the best feature of the java API and most 3th party API in java. In fact back when I learn C I was using the borland C compiler and it's build in help had an example for each call, which is even better then what most java api's give. Now we should not fail into stupid documentation like "this method is to set variable foo which is of type Foo" but a good integration with help() is nice for the proxy code (identity,scheduler,etc.) and the main API which depends on a live request it's harder although we should look at how Robert did it for CP3 http://www.aminus.org/blogs/index.php/fumanchu/2007/01/20/help_cherrypy_3_0 Confining efforts to those facets that are uniquely TurboGears seems > logical. SO docs may be sub-par. (Actually, I find them to be OKish, > but I know others might disagree.) but the first priority should > probably be the core. that is my opinion too. Just to get my input in on what I find most helpful in an API > reference, I'll mention that a nice dry and boring description of what > the call does, what the arguments and attributes do, etc. followed by > a single short example of the call being used, really helps, IMO. (Not > a complete usage case! Just what that particular line might look like > in a larger example.) The dry part is the most important. But if a > picture is worth a thousand words, an example is worth at least a > couple of hundred. yes indeed. I'll also point out that epydoc is not absolutely necessary to greatly > improve the situation with widgets. If the documentation within the > widget code is complete, and pushed out into a new bug fix release, > the widget browser would be a far more useful reference than it is > now. yes most API docs regarding widgets are not for "users" but for people actually developing widgets most people are happy with a nice commented Widget class and WidgetList so they can extend them and implement their own thing. The biggest issue with widgets is that they land in a fussy way between the model and the controller and most people are confused of what exactly to do with them (because they have a very big array of funtions starting with organizing your CSS/javascript to building forms) I'll not comment on beginners' docs or developers' docs. Not because > I don't think they are important. But because I'm in less of a > position to say anything useful on those fronts. > > Great thread, btw. :-) > --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
