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

[Valentino Volonghi aka Dialtone]

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.

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.

>-- 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.

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

Maybe it's too concise. Every word in the current documentation must be carefully
read because it's meaning is incredibly important to actually understand the text.
Some things are implicit in the meaning given to that word and are never explained.

>-- 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.

Yes, that's what I mean by 'concise'.

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

This is another 'defect'. Twisted developers are extremely capable in python and
they tend to use the language as much as possible. Of course this requires the
same knowledge from the reader.

In my opinion this is a good thing overall, the only problem is that sometimes
docstrings are missing and this makes reading code harder than it could be.

HTH :)