Changes between Initial Version and Version 1 of DocumentationAnalysis/Threads/MaryGardiner

02/24/2006 09:58:47 PM (10 years ago)



  • DocumentationAnalysis/Threads/MaryGardiner

    v1 v1  
     1= Review details =
     3 * Link to document:
     4 * Reviewer's name: Mary Gardiner
     5 * Review date: 14 January 2006
     7= User profile =
     9 * Years using some parts of Twisted: 3
     10 * Overall level of comfort with Twisted: Reasonable amount
     11 * Level of experience with the subject matter of this document: Reasonable amount
     12 * Have read or used this document before: No
     14= Document expectations =
     16== Prerequisites ==
     18 * Someone who has been exposed Twisted's core event model: that is, the reactor and Deferreds.
     19 * Someone who is relatively new to Twisted, and whose understanding of the above may not be totally solid.
     21== Outcomes ==
     23 * When to use threads in Twisted: the kind of situations which require it, and the kind of situations in which it is a reasonable option.
     24 * How to use threads in Twisted: the major API functions or whatever.
     26= Document review =
     28''As you read the document, begin filling this out''
     30== Prerequisites ==
     32Overall, I felt that this document's prerequisites matched my expectations reasonably well
     34Some specific examples where there seems to be some assumed knowledge include:
     36 * threads are mentioned without any introduction or links
     37 * thread safety is mentioned without any introduction or links
     38 * Deferreds are mentioned without any introduction or links
     40== Outcomes ==
     42Things I learned/I think someone would learn from this document are ''[be specific]'':
     44 * the major threading APIs in Twisted
     46Things that I think this document tries to teach people but that I couldn't understand by using it:
     48Nothing of note.
     50== Content suggestions ==
     52The following additions to and changes to the content would improve this document:
     54 * some links to other Twisted event documents (eg the async stuff) would not go astray
     55 * likewise, perhaps a link to a third-party document explaining exactly what threads are
     56 * the whole question of when you might want to or need to use threads (mainly for third party APIs that block) is only very briefly touched on: this should be a whole section
     57 * an explanation of, or link to an explanation of, what is meant by "thread safe"
     58 * is there a reason that there's emphasis on the utility methods being in a different module?
     59 * the APIs need to be linked to, not just mentioned
     61== Style ==
     63The following changes to the style of the document would make it easier to read:
     65 * This sentence is rather convoluted: "For functions whose results we wish to get, we can have the result returned as a Deferred:". It might be better worded as something like: "If we want the result of the function run in a thread, the deferToThread method returns a deferred which will be fired with the result