Changes between Initial Version and Version 1 of DocumentationAnalysis/ExpertReviewTemplate

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



  • DocumentationAnalysis/ExpertReviewTemplate

    v1 v1  
     1This is a '''template''' for experts in 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.
     3Things in ''italics'' get replaced with your own text or removed.
     5''How to review: as you go to the document, think very careful about the '''intended user''' (the template asks you to describe the intended user, and eventually this information will go into the document itself in some form). Think of the type of person you would love to hand this document to. Think of the type of questions on IRC that you'd love to be able to say "go to http://blahblahblah and see section 3".''
     7''What do these users know already? What do they think they know and are likely to actually be confused about? What don't they know that you want this document to teach them?''
     9''This is the purpose of the document. Any bit of text you read and any example in the document should be able to be explained in terms of either clarifying the user's understanding or teaching them something relevant and new. (Anything that's there and not doing one of these two things is presumably serving some other purpose of the author's and you might want to consider whether this purpose is worthy of its own document. Otherwise it should be removed.)''
     11''Recall that the intended user of this review itself is a documentation writer, and your role as a reviewer is to make their job easier. Therefore address problems that it is a writer's job to fix (mistakes, missing information, irrelevant digressions) and not problems that an improved document can't help with (say, the lack of common sense, imagination and intelligence in people you have cause to interact with on a day-to-day basis).''
     13= Review details =
     15 * Link to document: ''''
     16 * Reviewer's name: ''Jane Bloggs''
     17 * 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)''
     19= Document expectations =
     21''Fill this out '''before''' you read the document, based on the title of it. This gives us a good idea of what's missing.''
     23== Intended user ==
     25Before someone begins using this document, I'd really really like it if they knew:
     26 * ''the fundamentals of the server/client model''
     28 * ''the basics of the HTTP GET request''
     29 * ''component architecture design''
     31== Outcomes ==
     33Once someone has read this document they should understand ''[this list can be quite long if you like, you're really writing a specification for the document]'':
     34 * ''that having a function return a Deferred doesn't make it asynchronous''
     35 * ''that the Application framework can be used to avoid a lot of server setup boilerplate''
     37= Document review =
     39''Have a look at wiki:DocumentationAnalysis/UserReviewTemplate for an alternative review style you might prefer.''
     41== Coverage of subject matter ==
     43''Documents should demonstrate and recommend only '''best practice''', except in clearly marked examples of bad code which leads to a justification of best practice. Any out-of-date or questionably intelligent ways of doing things shown in our documentation are problems. Best practice should be exhibited even when it makes examples longer.''
     45'''''Best practice''' includes: code doing what it puports to do; following Twisted coding style; using accepted idioms; and unless the documentation is to demonstrating a lower level feature by reimplementing a higher level one it should use appropriate library functions (eg LineReceiver) instead of doing a half-baked reimplementation. Further, code should be '''easily readable''' at the expense of lines of code -- code is more readable when the number of things it does per line is limited.''
     47This document seems to cover the following subject matter at least acceptably well:
     48''list here''
     50This document seems to be attempting to cover the following subject matter, but its coverage is flawed:
     51 * ''example 3 puports to demonstrate a webserver, but does not in fact run''
     52 * ''section 2 says that the design of X solves Y problem when it actually doesn't''
     53 * ''example 7 is using a sequence of functions to get Y result when we actually provide a convienience function Z''
     55This document ought to be covering the following subject matter but is not:
     56 * ''the reason why Y is a better design than Z in this case''
     57 * ''Foo useful library function''
     58 * ''the X class of problems for which this approach needs to be modified''
     60This document is recommending the following things that it shouldn't be recommending: ''[recall that merely mentioning something in a document often counts as a recommendation, and mentioning something only to denounce it is confusing and should be limited]'':
     61 * ''X out-of-date library function''
     62 * ''Y sequence of calls which have been superceded by Z library''
     64This document could be supplemented by links to these existing pre-requisitie ("you should read this first") documents:
     65''list here''
     67This document could be supplemented by links to these existing follow-up ("now that you know X you can try Y") documents:
     68''list here''
     70This document could be supplemented by as-yet non-existant pre-requisite ("you should read this first") documents on:
     71''list here''
     73This document could be supplemented by links to these as-yet non-existant follow-up ("now that you know X you can try Y") documents:
     74''list here''
     76== Style ==
     77The following changes to the style of the document would make it easier to read:
     79 * ''shorter paragraphs in section 4''
     80 * ''less hyperbole about the Twisted Way in the introduction''
     82== Overall summary ==
     84This document is: ''excellent / good, with some minor improvements to recommend / reasonable, with some pretty obvious improvements to make / better than having no documentation, but with some glaringly obvious improvements to make / so bad that it would be better to have no documentation on this''