On 5/6/05, <b class="gmail_sendername">Eugene Coetzee</b> <<a href="mailto:projects@reedflute.com">projects@reedflute.com</a>> wrote:<div><span class="gmail_quote"></span><div><br>
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Twisted is a superb framework. Once I took a few days of and hacked my<br>way through its enigmatic depths I also whispered to myself ...
<br>eureka... I'm not sure though that documentation is the *only* problem.</blockquote><div><br>
Maybe maybe not. But right now the documentation is like a lightning
rod. No matter what your agenda, if you want to (for whatever reason)
discourage against the use of Twisted in a project, all you have to do
is point to the documentation and the frazzled bunch of geeks trying to
figure it all out :-)<br>
</div><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">My experience tells me that basic concepts around the "networking layer"
<br>
is intimidating to a lot of developers.</blockquote><div><br>
It would not hurt to have some nice top level documents to address
that. That's the sort of thing you'd derive from design documentation. <br>
<br>
</div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">I normally ask myself how long will it take to understand this stuff -<br>given the state of the documentation. Then I compare it to how long it
<br>would take to write it myself. Lets be frank - "open source" assumes to<br>an extent that you would actually "read the source" as part of the<br>documentation. To me the detail (like the API) is not the problem.
</blockquote><div><br>
I would have to disagree on that on a fine point. Twisted is not "open
source software that happens to be a network framework". It is a
"network framework that is also open source software". I didn't
start looking at Twisted because it was open source. I started looking
at it because I was interested in a better answer than I currently had
for networking.<br>
<br>
AS SUCH ... I expect the API, like any library I use, to be properly
documented so I can start using it. I do not wish to investigate the
source code as a recreational thing. I have a job to do and I want to
get it done on time, on budget, and done well. Making source code
delving a prerequisite to use of the software is bad form, in my
opinion.<br>
<br>
Yes, I find having the source code useful. Usually it's because the
documentation leaves a fine point unclear; examining the source may
resolve the confusion. But the source code should not be a crutch to
support incomplete documentation - not if you want to go toe to toe
with the big dogs.<br>
</div><br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">I would love to see high level conceptual documentation to give me a<br>better idea of basic concepts like the "reactor", "application",
<br>"service", "transport","protocol", "factory" - what they are supposed to<br>do and how they are to fit together.</blockquote><div><br>
:: nod nod nod nod ::<br>
<br>
</div></div>-- <br><br>Best,<br><br> Jeff<br>