= Review details =

 * Link to document: http://twistedmatrix.com/projects/core/documentation/howto/threading.html
 * Reviewer's name: Mary Gardiner
 * Review date: 14 January 2006

= User profile =

 * Years using some parts of Twisted: 3
 * Overall level of comfort with Twisted: Reasonable amount
 * Level of experience with the subject matter of this document: Reasonable amount
 * Have read or used this document before: No

= Document expectations =

== Prerequisites ==

 * Someone who has been exposed Twisted's core event model: that is, the reactor and Deferreds.
 * Someone who is relatively new to Twisted, and whose understanding of the above may not be totally solid.

== Outcomes ==

 * 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.
 * How to use threads in Twisted: the major API functions or whatever.

= Document review =

''As you read the document, begin filling this out''

== Prerequisites ==

Overall, I felt that this document's prerequisites matched my expectations reasonably well

Some specific examples where there seems to be some assumed knowledge include:

 * threads are mentioned without any introduction or links
 * thread safety is mentioned without any introduction or links
 * Deferreds are mentioned without any introduction or links

== Outcomes ==

Things I learned/I think someone would learn from this document are ''[be specific]'':

 * the major threading APIs in Twisted

Things that I think this document tries to teach people but that I couldn't understand by using it:

Nothing of note.

== Content suggestions ==

The following additions to and changes to the content would improve this document:

 * some links to other Twisted event documents (eg the async stuff) would not go astray
 * likewise, perhaps a link to a third-party document explaining exactly what threads are
 * 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
 * an explanation of, or link to an explanation of, what is meant by "thread safe"
 * is there a reason that there's emphasis on the utility methods being in a different module?
 * the APIs need to be linked to, not just mentioned

== Style ==

The following changes to the style of the document would make it easier to read:

 * 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