home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 October / usenetsourcesnewsgroupsinfomagicoctober1994disk2.iso / reviewed / guide-rev next >
Internet Message Format  |  1992-08-05  |  10KB
  1. From: Andrew Patrick <csr@calvin.dgbt.doc.ca>
  2. Subject: v02INF11: guide-rev - Reviewing Guidelines for comp.sources.reviewed
  3. Newsgroups: comp.sources.reviewed
  4. Approved: csr@calvin.dgbt.doc.ca
  5.  
  6. Submitted-by: Andrew Patrick <csr@calvin.dgbt.doc.ca>
  7. Posting-number: Volume 2, Info 11
  8. Archive-name: guide-rev
  9. Supersedes: guide-rev: Volume 2, Info 4
  10.  
  11.                          Comp.Sources.Reviewed
  12.                         Guidelines for Reviewers
  13.                              (Version 1.9)
  14.  
  15. This document is designed to provide guidelines and suggestions for use
  16. while reviewing software for the news group "comp.sources.reviewed".
  17. It also provides potential submitters with information about what the
  18. reviewers will be looking for, and may be useful to others who are
  19. asked to evaluate software.
  20.  
  21. These guidelines may change as we gain more experience in reviewing
  22. software, and comments are welcome.
  23.  
  24.  
  25. Getting Submissions to Review
  26. -----------------------------
  27.  
  28. Comp.sources.reviewed (CSR) uses a volunteer system for assigning
  29. sources to reviewers.  When submissions come in, a Call For Reviewers
  30. (CFR) is prepared describing the software and the kinds of equipment and
  31. expertise that is needed to test it.  This CFR is sent to each of the
  32. potential reviewers and if you are interested, the entire submission is
  33. sent to you.  Thus, you have complete control over what you review.  You
  34. are also able to volunteer for reviews at the times when you are not too
  35. busy with other things.
  36.  
  37. Given this procedure, it is expected that you return your reviews in a
  38. reasonable period of time.  If you find that you cannot provide a review
  39. of a submission in reasonable amount of time (say 1-2 weeks), then
  40. please inform the moderator so he does not waste time waiting for you.
  41. Also, if you find that once you get the package you cannot review it
  42. because of missing equipment or expertise, please inform the moderator
  43. as soon as possible.
  44.  
  45.  
  46. Record Your Work
  47. ----------------
  48.  
  49. A crucial part of the review process is recording what you do.  You
  50. must make complete and accurate notes of your time spent working on the
  51. package.  Don't rely on your memory to record the problems or
  52. suggestions you come across, because you will forget quickly as you
  53. move on to other things.  So, the first thing to do when you get a
  54. submission is to start documenting everything that happens.  Since you
  55. will probably be working on several machines, you may have to work with
  56. pencil and paper (gasp).
  57.  
  58.  
  59. Evaluating the Format of the Submission
  60. ---------------------------------------
  61.  
  62. Was it in the form of a "shar" file, or similar packaging appropriate
  63. for the architecture?
  64.  
  65. Did in unpack correctly?  
  66.  
  67. Did it unpack in the places you expected it to?
  68.  
  69. Did it contain a MANIFEST file listing all the parts of the
  70. submission?
  71.  
  72.  
  73. Evaluating the Description and Purpose
  74. --------------------------------------
  75.  
  76. Is there a README file that contains: 
  77.  
  78.    - the purpose and value of the software (give details here)
  79.    - the types of systems it is intended for (e.g., BSD only,
  80.      Unix and DOS, etc.)
  81.    - any dependencies in the system (e.g., must have perl to
  82.      run)
  83.    - known limitations of the software
  84.    - the authors of the software (with e-mail addresses)
  85.    - the "patchlevel" of the software (see below)
  86.    - any copying or distribution conditions
  87.  
  88. Is there a "patchlevel.h" file (or equivalent) indicating the version
  89. number of the software?
  90.  
  91.  
  92. Building the Software
  93. ---------------------
  94.  
  95. Is there an Installation document explaining how to build the software?
  96.  
  97. Are the options and conditional parts of the package (e.g., do this for
  98. DOS, this for System V, etc.) clearly documented?
  99.  
  100. Is there a proper Makefile? (Imakefile for X software?)
  101.  
  102. Did the make run correctly?
  103.  
  104. Are building and installation two separate steps?
  105.  
  106. Did the software build on each of the architectures you were able to
  107. test?  
  108.  
  109.     NOTE: It is important that you give details about the environments
  110.     you used for testing in each and every review that you do.  Make
  111.     sure you describe the hardware, OS, compilers, etc.  that you used,
  112.     and any other information that is relevant.  This information will
  113.     be used to evaluate the portability of the package, and will be
  114.     posted along with the sources to let the readers know if the package
  115.     is appropriate for them.
  116.  
  117.  
  118. Testing the Software
  119. --------------------
  120.  
  121. Did the software run on each of the systems you tested?
  122.  
  123. Did the program perform the functions it was supposed to perform?
  124.  
  125. It is not your place to fix the software you are reviewing.  However, if
  126. you find a problem with an obvious solution, make sure you document it
  127. so the authors can make use of it.
  128.  
  129.  
  130. The Documentation
  131. -----------------
  132.  
  133. The documentation is a very important part of a submission, so it
  134. should be reviewed carefully.  The documentation may be built-in to the
  135. program and be in the form of document files and/or man pages.  It is
  136. difficult to give simple rules for documentation, and not all programs
  137. require the same amount of documentation, but here are some things to
  138. consider.
  139.  
  140.     General Guidelines
  141.     ------------------
  142.  
  143.     Is the documentation written in a form that is clear, precise, and
  144.     easy to understand?
  145.  
  146.     Is each feature or function of the program documented?
  147.  
  148.     Is the documentation organized?  Sections and sub-sections often
  149.     make documents easier to read and understand.
  150.  
  151.     Documentation should be provided in "text only" form.  An author may
  152.     choose to also provide formatted manuals that use PostScript or TeX,
  153.     but a readable form should be provided.
  154.  
  155.  
  156.     Guidelines for Unix Documentation
  157.     ---------------------------------
  158.  
  159.     Is there a man page?  Man pages should contain the following
  160.     sections (at least):
  161.  
  162.     NAME             required
  163.     SYNOPSIS         required
  164.     AVAILABILITY     optional
  165.     DESCRIPTION      required
  166.     OPTIONS          required if there are any command-line options
  167.     ENVIRONMENT      required if there is provision for environment 
  168.                      variables
  169.     FILES            required if use is made of other files
  170.     SEE ALSO         optional
  171.     DIAGNOSTICS      required if the program can produce debugging output
  172.     NOTES            optional
  173.     BUGS             required if any are known
  174.     AUTHOR           optional
  175.  
  176.     These sections should be complete (e.g., all the OPTIONS must be
  177.     described).
  178.  
  179.  
  180.     Guidelines for VMS Documentation
  181.     --------------------------------
  182.  
  183.     Is there a VMS HELP file?  HELP files should contain the following
  184.     sub-topics (at least):
  185.  
  186.     Parameters             if there are any
  187.     Command_Qualifiers     if there are any
  188.     Examples               if appropriate
  189.  
  190.     Is there additional documentation to supplement the VMS HELP file?
  191.  
  192.  
  193.     Guidelines for DOS Documentation
  194.     --------------------------------
  195.  
  196.     There are no standards for DOS documentation, and this makes the
  197.     review process difficult.  We suggest that the information and
  198.     features described above should also be present in DOS
  199.     documentation, although they may not be in the form described
  200.     above.
  201.  
  202.  
  203. Functionality and Features
  204. --------------------------
  205.  
  206. Does the software perform some function that is valuable?
  207.  
  208. Are there obvious features or additions that would improve the package?
  209.  
  210.  
  211. Overall Evaluation
  212. ------------------
  213.  
  214. What is your overall evaluation -- would you recommend it to a friend?
  215.  
  216. Would you suggest that this submission:
  217.  
  218.    - be accepted for posting as is
  219.    - be accepted after minor revisions (that you have detailed)
  220.    - be returned to the author with a recommendation to make
  221.      major changes and re-submit
  222.    - be rejected
  223.  
  224.  
  225. Short Summary of Review
  226. -----------------------
  227.  
  228. Regardless of your recommendation for the submission, you should
  229. provide a short summary (one or two paragraphs) of your review.  If the
  230. package is posted, this summary will be posted with it.  Otherwise, it
  231. will be used by the moderator to determine the appropriate action to be
  232. taken with a submission.  This summary might mention why you found the
  233. package useful, what you liked about it, what machines you tested it
  234. on, and what limitations you did find.  Your name will not be attached
  235. to this review summary when it is returned to the authors or posted.
  236.  
  237.  
  238. Submitting Your Review 
  239. ----------------------
  240.  
  241. The final step is to return your review to the moderator.  Please make
  242. sure you quote the "reference name" in your summary, preferably in the
  243. subject line.
  244.  
  245. DO NOT send your review to the author.  The moderator will collect
  246. all the reviews, prepare a grand summary, and forward it to the author.
  247. You will get a copy of this grand summary to allow you to compare your
  248. work with other people's reviews.
  249.  
  250. Your review should provide as much detail as possible.  Make sure you
  251. give details on the kinds of machines you tested on.  You may choose
  252. to use this file as a template to record your review.
  253.  
  254. Contacting the Authors
  255. ----------------------
  256.  
  257. Your identity will not be revealed to the authors unless you choose to
  258. do so.  If you feel that you would like to contact the authors for
  259. clarification, you may contact them directly or ask the moderator to
  260. forward your question.  You should only contact the author for
  261. clarification or additional information needed to complete your
  262. review.  You should not comment on the submission at this time, but
  263. instead save your comments for the report you send to the moderator.
  264. You should also ensure that your interactions with the author are
  265. conducted in a courteous and professional manner.
  266.  
  267. In addition, you should ensure that the other reviewers working on that
  268. submission also receive the information you get back from the authors.
  269. Further, you must do so in a manner that does not interfere with their
  270. wishes not to identify themselves to the authors.
  271.  
  272. It is not a good idea to suggest that authors make patches to software
  273. during the review process.  If you find a problem that the authors are
  274. able to fix easily, document the problem and suggest that minor
  275. revisions are needed before the submission is posted.  It is important
  276. that you are not evaluating software that has been patched, while others
  277. are working with the original submission.
  278.  
  279. You should not send the author any comments about, or evaluation of, the
  280. submission.  That information should be sent to the moderator in your
  281. final summary, and he will collect the comments from all the reviewers
  282. and forward them to the author if appropriate..
  283.  
  284.  
  285.