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

L. Daniel Burr ldanielburr at mac.com
Fri Jul 7 08:36:25 CDT 2006


On Fri, 07 Jul 2006 07:10:51 -0500, Valentino Volonghi aka Dialtone  
<dialtone at divmod.com> wrote:

> On Thu, 6 Jul 2006 15:34:16 -0400 (EDT), lloyd at paisite.com wrote:
>> 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?
>
> I don't think we can be satisfied but unfortunately IMHO the real  
> problem with
> twisted is not twisted itself but the big shift in the way you should  
> think
> that drives away most people. I know many intelligent and very capable
> programmers that do understand twisted (or are able to) but they do not  
> intend
> to learn it because they feel it's hard while threading isn't as hard as  
> we
> picture it. Having more and better documentation will help, many graphs  
> about
> how things actually work _DO_ help but you can do only so much to attract
> new people.
>

I think that worrying about attracting an audience that prefers to use the
thread-based approach is doomed to failure, in the same way that inviting
a conservative to adopt liberal ideals is doomed to failure.

> One of the most needed things is to collect a page inside twisted  
> documentation
> about the many reasons why threading is harder than the twisted approach  
> and
> why. Currently there are many documents that try to explain this at  
> various levels
> but a single, clear and simple one is missing. Even writing two  
> alternatives
> using the two different models could probably help.
>

I don't think this would help much either, in that people who like to
use threads most definitely do *not* see them as being harder to use
than the twisted approach; on the contrary, they find threads to be far
more natural to their way of thinking, and most of them have never run
into the kinds of serious problems that threading can introduce.  I
sincerely believe that until a person actually encounters a serious
thread-related problem, they cannot be convinced to adopt anything that
does what twisted does.

>> -- 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?
>
> I don't think I can answer this question. When I first learnt twisted I  
> used
> the documentation and found it pretty good.
>

I have to agree here.  I have used twisted since the 0.9 days, and I have
always found the documentation to be perfectly adequate.  Honestly, while
I recognize that the vast majority of interested parties find the docs to
be incomplete or confusing, I have never had the problem, and so I am
struggling somewhat in understanding how to solve it.

Note that I am the furthest thing from an expert programmer, in any field,
so I don't think the "only really smart people can understand twisted"
argument doesn't hold in my case.  Quite the opposite, actually; I use
twisted because it solves a lot of the hard problems for me, and I can
just concentrate on my application.

Perhaps the problem is that the twisted docs primarily teach the theory
of operation (Deferreds, Protocols, etc.).  For someone like myself, the
theory of operation is exactly what I want to know.  For others, I suspect
there is more value in documentation that covers things of a very specific
nature, such as "how to build a web application that talks to a database",
or "how to build a DNS server", or other such use-case-oriented fare.

If so, then the real problem is that using twisted requires you to learn
the underlying structure (Deferreds, Protocols, etc) before you can get
started on your application.  There is a movement these days in many
projects to get the user up and running without any prior understanding,
the thinking being that they will pick up the details later, as needed.
Personally, my brain doesn't work that way, but I know many people who
cannot tolerate my approach, and find it unbearably slow.

So, maybe a "Build a real, working, application in 15 minutes" is the
kind of fare needed to make twisted more palatable to the audience that
is currently being frustrated in achieving twisted zen.

L. Daniel Burr



More information about the Twisted-web mailing list