Changes between Initial Version and Version 1 of DocumentationAnalysis/UserReviewTemplate


Ignore:
Timestamp:
02/24/2006 09:58:47 PM (8 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DocumentationAnalysis/UserReviewTemplate

    v1 v1  
     1This is a '''template''' for users of Twisted to use when reviewing documents as part of the DocumentationAnalysis project. See wiki:DocumentationAnalysis/DocumentList for further instructions about what to do with this template. 
     2 
     3Things in ''italics'' get replaced with your own text or removed. 
     4 
     5''How to review: go through the document trying to '''use''' it. Read each section and see if you can work out why it's there and what it's trying to tell you and if you understood that. Have a look at each example, try to run it and figure out if: you have any idea what that kind of code would be useful for; and whether you could customise it for your own needs.'' 
     6 
     7''Be '''critical''': as you read, watch yourself. If you're puzzled by something, feel confused, feel stupid, or just have niggling worries about why X was introduced, or why Y is such a good way of doing things, these are things we want to know. Assume that these kinds of problems are '''the document's fault''', not yours.'' 
     8 
     9''Be '''helpful'''. This review is a document you are writing to explain yourself and your documentation needs to us. Our documents may in parts be confusing, misleading, useless or patronising. The correct response to the frustration this causes is to write a clear, calm review explaining what you need from this document that it didn't give you. Documentation writing is an art; just because the writer knows Twisted better than you doesn't mean they understand your needs nearly as well as you. If they haven't explained Twisted to you, you need to explain yourself to them.'' 
     10 
     11= Review details = 
     12 
     13 * Link to document: ''http://twistedmatrix.com'' 
     14 * Reviewer's name: ''Jane Bloggs'' 
     15 * Review date: ''14 January 2006 (please don't use locale specific dating styles, ie not 1/14/06 or 14/1/06, it's confusing)'' 
     16 
     17= User profile = 
     18 
     19 * Years using some parts of Twisted: ''2'' 
     20 * Overall level of comfort with Twisted: ''None, Very little, Reasonable amount, Heaps'' 
     21 * Level of experience with the subject matter of this document: ''None, Very little, Reasonable amount, Heaps'' 
     22 * Have read or used this document before: ''Yes or No'' 
     23 
     24= Document expectations = 
     25 
     26''Before reading the document, note down anything you were expecting to find in it.'' 
     27 
     28== Prerequisites == 
     29 
     30''Who do you expect the document to be aimed at, eg "someone who knows Python and some networking basics", "someone who is familiar with the Application framework", "someone who understands Twisted basics and HTTP"''' 
     31 
     32== Outcomes == 
     33 
     34''What do you expect to learn from this document? eg "what Twisted is", "what Twisted is good for", "what Deferreds are and how to use them", "asynchronous programming basics", "how to write an HTTP server that has a custom backend"''' 
     35 
     36= Document review = 
     37 
     38''As you read the document, begin filling this out'' 
     39 
     40== Prerequisites == 
     41 
     42''As you go through the document, compare your expectations with the reality. Depending on your own experience, it might be that you just couldn't understand a part of the document and have no idea what would help. Or you might be able to muddle through. In either case, you should mention that here.'' 
     43 
     44Overall, I felt that this document's prerequisites matched my expectations ''[well/badly]'' 
     45 
     46Some specific examples where there seems to be some assumed knowledge include: 
     47 
     48 * ''The 'basics' section talked about interfaces as if I should know what they are'' 
     49 * ''I had no idea how to get example 2 running, I tried X, Y and Z'' 
     50 * ''the example of a web server that serves static pages assumes that you know about components and how to do a custom implementation of an interface'' 
     51 * ''example 3 suggested that I could use Foo class to write a nameserver, but examples 4, 5, and 6 all used Bar class instead and I don't know why'' 
     52 
     53''A person working with this section of your review might use your review to link to other documents more extensively to help people out, or they might use it to expand some sections of the document, or remove some extraneous stuff.'' 
     54 
     55== Outcomes == 
     56 
     57''List things that you think you got (or if you know the material already, someone learning would get) from this document:'' 
     58 
     59Things I learned/I think someone would learn from this document are ''[be specific]'': 
     60 
     61 * ''how to get results out of Deferreds'' 
     62 * ''writing a webserver backend'' 
     63 
     64Things that I think this document tries to teach people but that I couldn't understand by using it: 
     65 
     66 * ''the design tradeoffs that led to the development of Deferreds'' 
     67 * ''reasons why one might create a tree of ServiceCollection and Service objects'' 
     68 
     69''[If you know this part of Twisted only].'' Useful classes/examples/explanations that seem to be completely missing from this document are: 
     70 
     71 * ''the alternative Foo class implementation'' 
     72 * ''the foo() convienience function that eliminates most of the boilerplate in example 3'' 
     73 
     74== Content suggestions == 
     75 
     76''Here, make suggestions for content you'd like to see included. Where possible, make positive suggestions. Try to avoid saying things like "a better webserver" or "some good examples" though: of course we want our documents to be good; or better, but we need you to explain how to do that.'' 
     77 
     78The following additions to and changes to the content would improve this document: 
     79 
     80 * ''an explanation of why Twisted designed the code so that I have to do X'' 
     81 * ''an explanation of the tradeoffs between choosing class Foo and class Bar to do task X'' 
     82 * ''an example of a webserver that doesn't have static files as its backend'' 
     83 * ''a fixed example 3 that does [fixed thing] instead of [broken thing]'' 
     84 * ''replace section 5 with a reference to document Foo, which explains Bar so much better'' 
     85 
     86== Style == 
     87 
     88The following changes to the style of the document would make it easier to read: 
     89 
     90 * ''shorter paragraphs in section 4'' 
     91 * ''less hyperbole about the Twisted Way in the introduction''