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

02/24/2006 09:58:47 PM (9 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