[Twisted-Python] Documentation

Glyph Lefkowitz glyph at twistedmatrix.com
Tue Aug 11 15:03:10 MDT 2009


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 :).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20090811/fc75f7cd/attachment.html>


More information about the Twisted-Python mailing list