On Mon, Aug 10, 2009 at 2:56 AM, John Aherne <span dir="ltr"><<a href="mailto:johnaherne@rocs.co.uk">johnaherne@rocs.co.uk</a>></span> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
Prompted by exarkun, I have put together some simple documentation for beginners starting with Twisted.<div></div></blockquote><div><br>Thanks for doing this. All documentation help is useful :).<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;">
<div>But before I spend more time on honing the document, I thought it would be a good idea to get some feedback.
<div></div></div></blockquote><div><br>I've added a review of this document to my personal to-do list, but that might take another couple of days.<br><br>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,<br>
<br><blockquote style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;" class="gmail_quote">For simple network activity you do not need to use deferreds<br></blockquote><br>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 <i>why</i> they don't need Deferreds.<br>
<br>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 :).<br>
</div></div>