johnaherne at rocs.co.uk
Wed Aug 12 06:41:18 EDT 2009
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
> 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.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Twisted-Python