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

[lloyd at paisite.com]

Hello,

On Sun, July 2, 2006 9:15 pm, Terry Jones wrote:
> Here's a summary of thoughts I've had over the last month or so.

As one totally smitten with Twisted but compelled to abandon it due to
lack of documentation, I heartily second Terry Jones's critique and
proposal.

I tried to contribute my small bit toward better Twisted documentation
with the Techno Turkey Adventures series... even created a Techno Turkey
blog.

My assumption was that by starting from a know-nothing stance and asking
embarrassingly naive questions I could tease out enough technical
direction to build enlightening and useful code experiments designed to
accelerate progress up the Twisted learning curve.

But several things brought the endeavor to a premature end:

1) My own limited Python skills meant that I couldn't, on my own hook, dig
much meaning out of the source code. There are a number of Python (or,
perhaps, object) idioms used extenstively in the Twisted corpus that
totally baffle me.

2) I never could get a grasp of the big picture -- how all the parts fit
together -- or don't. Starting from the Twisted root, the corpus seems to
branch out prolifically -- some branches fairly complete and useful, some
under active development, and some abandoned. I just couldn't tell which
was which.

3) Several people from the Twisted community generously offered guidance
and support. Of those, all but one knew little more than I did. These
stalworthy folks helped enormously with testing and identification of
various copy and code errors, but couldn't lead me toward forward
progress. The one person who knew his way through the thicket the way was
more than generous with his suggestions, but too time-constrained to give
much in the way of big picture.

By and large, I had the feeling that the core Twisted developers were
moving so fast exploiting Twisted and progeny commercially, that they had
little time for documentation or bringing others along behind them. No
complaint here; just stating a perception.

4) My own time constraints imposed severe limits on the time I could
commit to the projectd. As a result, I just couldn't learn enough fast
enough to meet a deadline I had for a web project of my own. The result, I
turned to another Python web framework and was able to make significant
progress within days -- not because the framework (Karrigell) was better
documented, but because it so was far less ambitious -- simple-minded even
-- that even a turkey like me could understand it.

I would like to return to Twisted. Indeed I would like to pick up the
Turkey series again if it is deemed helpful to the community. But to do so
I would need one or more talented technical mentors to keep me on a
productive path.

If not Turkey, then I'm still willing to provide all the help I can, given
my limited technical perspective, toward better Twisted documentation.
But, again, as a follower, not a leader.

Cheers, Terry. I'm pulling for your success.

Best wishes,

Lloyd R. Prentice