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