[Twisted-Python] Documentation

[John Aherne]

On Tue, Aug 11, 2009 at 10:03 PM, Glyph Lefkowitz
<glyph at twistedmatrix.com>wrote:

> On Mon, Aug 10, 2009 at 2:56 AM, John Aherne <johnaherne at rocs.co.uk>wrote:
>
>> Prompted by exarkun, I have put together some simple documentation for
>> beginners starting with Twisted.
>>
>
> Thanks for doing this.   All documentation help is useful :).
>
>
>> But before I spend more time on honing the document, I thought it would be
>> a good idea to get some feedback.
>>
>
> I've added a review of this document to my personal to-do list, but that
> might take another couple of days.
>
> In the meanwhile, I think the stuff you're trying to communicate is
> valuable, but some of it seems pretty vague, and the ordering is a little
> confusing.  For example,
>
> For simple network activity you do not need to use deferreds
>>
>
> what constitutes "simple" network activity?  Does this means that there are
> some types of network activity do require deferreds?  For that matter, is
> "network activity" everything Twisted does, or just sending/receiving
> bytes?  etc, etc.  I think it would be better to clearly and simply lay out
> how to do "simple" network operations like sending and receiving data before
> talking about Deferreds at all.  It may still be useful to say "you don't
> need Deferreds" at some point, to make sure this is clear to the new user,
> but that should come later, when you can illustrate more clearly *why*they don't need Deferreds.
>
> You also use the word "seem" a lot.  You should be more assertive, and just
> say what things are or aren't, not what they seem like.  Don't worry about
> being wrong.  If you write something wrong, we will correct you before it
> goes into the docs :).
>
> _______________________________________________
> Twisted-Python mailing list
> Twisted-Python at twistedmatrix.com
> http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
>
> Thanks for taking a look.

I appreciate it it was a bit confused, but I wanted to get it out sooner
rather than later and just get the basic facts confirmed.

So I will start putting my thoughts into better shape and more coherently.
This always takes a couple of rewrites, so I hope you can add some more
thoughts before I get too far.

John Aherne
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20090812/1542fab7/attachment-0001.htm