On Fri, 7 Jul 2006 13:13:48 -0400 (EDT), [EMAIL PROTECTED] wrote:
Note that I have not looked at the documentation in nearly a year; it may very well have improved substantially since then.
Indeed it has but not enough probably.
Code that I can enter, run, and experiment with is definitely helpful in my case. One of the problems that I have with many of the code examples in the Twisted docs is that I don't understand what they're intended to do nor why I would want to do it. May very well be just the widget I need, but lack of context keeps me in the dark. I'm referring here to many of the examples in: http://twistedmatrix.com/projects/web/documentation/examples/
This is a matter of documenting examples... a problem pretty common with all the twisted-related frameworks I know.
I'm not sure I would call this a defect. We want developers to write the most efficient code possible. But if a world-class programmer needs less competent programmers to understand and/or support or use the code, then he/she is obligated to provide contextual documentation that communicates at a level that the code consumers can understand. And, if the programmer can't do it, then he/she would be wise to recruit/enlist competent documentation writers and spend the time necessary to help them understand what they need to know. I understand, of course, that in the all-volunteer open source army, this is a difficult thing to do.
It's harder the smaller the community is, the only fact that we are discussing about improving documentation means that the community is growing anyway.
Many thanks, Valentino, for your thoughtful consideration of the issue. Do you have the time and will to help me develop more Techno Turkey Adventures?
I wouldn't mind helping out, hopefully the discussion can take place in this mailing list so that other people (if they want) can help answering/completing/ fixing/evaluating what we write. Thanks for bringing up this topic anyway. _______________________________________________ Twisted-web mailing list [email protected] http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-web
