[Twisted-web] Re: Thoughts on documentation, wading into Twisted, Nevow, etc.

Valentino Volonghi aka Dialtone dialtone at divmod.com
Fri Jul 7 15:20:38 CDT 2006


On Fri, 7 Jul 2006 13:13:48 -0400 (EDT), lloyd at paisite.com 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.



More information about the Twisted-web mailing list