On Tue, Aug 11, 2009 at 10:03 PM, Glyph Lefkowitz <gl...@twistedmatrix.com>wrote:
> On Mon, Aug 10, 2009 at 2:56 AM, John Aherne <johnahe...@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@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
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
