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

lloyd at paisite.com lloyd at paisite.com
Thu Jul 6 14:34:16 CDT 2006


Hi Terry,

On Thu, July 6, 2006 1:25 pm, Terry Jones wrote:

> Thanks for all the very thoughtful replies to my long mail. I didn't mean
>  to whine about things and then just disappear back into the woodwork, I
> just have to deal with various other things right now. I'm thinking about
>  what I wrote, the various replies, what might be effectively done, etc.
> I
> hope to be able to follow up again soon.

I was one of the respondents to your much welcomed critique of Twisted
documentation.

And I would like to explore with you and others how to contribute toward
improved Twisted documentation.

Here's what I've done to date to make Twisted more available to the less
technially astute:

http://twisted.paisite.com.

For reasons good and bad the Techno project is stalled, but it might be
worth picking up again.

It seems to me that one of the first questions in software documentation
is: "Who are we writing for?"

Given that, the next question is: "Who much or how little can we assume
that our consumers already know?"

Several questions, then, for the Twisted community:

-- Are we satisfied with the current level of adoption of Twisted in new
projects; e.g. do we want to remain a relatively small commmunity of elite
developers and user or would we like to attract and build a broader
community?

-- Is the corpus of Twisted documentation as it stands sufficiently
serving the needs of the community or is it holding back our efforts
toward longer-term goals?

-- What, if any, are the shortcomings of current documentation?

-- Is it possible for us, given all constraints, to better organize our
efforts toward improved documentation and, if so, how?

Here's my personal experience with Twisted:

I spent considerable time last year studying Twisted documentation. I was
encouraged by an assertion that the Twisted developers were hoping for
widest possible adoption of the Twisted framework. But as I moved further
into the docs I discovered that much of it was written in a highly
specialized argot -- jargon or precise technical language I'll let someone
else decide. But, with full acknowledgement of my own inexperience and
shortcomings, much of it was completely incomprehensible to me.

And looking at the source code I found numerous syntactical constructs
that I simply couldn't penetrate.

Now, granted, I had and still have limited experience with Linux, Python,
and object architectures. But I was highly motivated to learn what I
needed to know to use Twisted in my own projects.

As I widened my studies and dug deeper I discovered yet another problem:
Trying to discern a roadmap through the Twisted thickets was like
following a well-paved road that turned into graded dirt then diverged
into countless sandy paths that then faded into the desert. After several
weeks pursuing the fractal-like tracks I, for one, felt stranded far from
water and shade.

What finally did me in was a severe electrical storm which blew out the
machine on which I was doing my Twisted experimentation.

Now I take full responsibility for my own intellectual and experiential
shortcomings. Fact is, many good people put countless hours into creating
the Twisted corpus of code and documentation. And I'm grateful for every
minute of it. If they didn't reach me, it's not their problem. It's mine.

But as your critique attests, backed by many others on the various lists,
I'm not the only one looking enviously in on the party.

I would have liked very much to have mastered, or at least sufficiently
understood Twisted, to integrate it into my own projects, but there was
simply not world enough nor time given the current state of docs.

Now, encouraged by others seeking improved Twisted documentation, I'm
delighted to offer again my limited skills toward that goal. But I need
folks with knowledge beyond mine to lay out the path and point the way.

All the best,

Lloyd R. Prentice
President
Prentice Associates Incorported












More information about the Twisted-web mailing list