ADMIN: RE: [Javascript] PROPOSAL for An Annotated JavaScript Project

[David Merchant]

Thanks for the feedback, glad there is interest in this.

Now for ironing out some of the details.  Those that are interested in 
participating, even if just occasionally or in a small way (I fully 
understand being busy or being spread thin), please give your comments / 
feedback / suggestions on the following items:

***  There are two ways I see that we can go about this (if there are other 
ways please bring them up for discussion):

1. Someone annotates every line in some script they wrote or like and 
either A) posts it for comments or B) I put it up on a special list members 
only web page where list members can add their comments to it.  Don't have 
to comment on every line, just on whatever line of the script they feel the 
need or have time to comment on.

2. A script is chosen, and is posted to the list or to the special list 
members only web page, and list members annotate as few or as many of the 
lines of the script as they choose or have time to.

There are pros and cons to either 1 or 2, and we could easily do both.  Do 
we prefer having the scripts and the annotations posted on the list, or by 
using a cgi script on a list members only page where list members can post 
their comments/annotations to parts or all of a script, adding theirs to 
whoever commented before them?

*** Need a way to end the process for a script (so that commenting and 
discussion and annotation for a particular script doesn't last for years 
:-) !).  Have some of us volunteer to be a board or panel that once a 
script becomes annotated and some sufficient time has passed, the 
board/panel votes on letting it be released to the public page that will be 
the repository for all the annotated scripts?  Any comments on this?

*** When the script is finished being peer-reviewed, it is placed on a 
public page for all the world to benefit from.

*** What scripts to choose?  For #2, I would suggest that we probably 
should concentrate at first on the most common basic scripts (image flips, 
etc).  For #1 any script a list member decides to annotate themselves and 
wants comments on.

*** Commenting: Let everyone be reviewers in good faith. That is, be 
polite, professional, and realize that often there are more than one right 
way to do the same thing.  It's OK to point out an alternative way of 
scripting a line or two of someone's code, and if there are short-comings 
in a line or so of coding that can be overcome by a different coding, by 
all means point it out (nicely!).  If there are short-comings or 
limitations in a script, by all means point that out too, that's part of 
the annotation and part of the learning process for us all.  For a "virgin" 
script that has no annotations and is being presented to the group for 
annotation/comments, whenever you comment or add any lines of annotations 
include your name to those annotations or comments so we can keep track of 
whose annotations get into the final version.

For those that annotate an entire script, after feedback and any changes, 
they of course can have their name as the annotator for that script (makes 
for a nice resume line item, and/or another page in your tenure file, 
etc).  For the scripts that are "virgin" and several members of the list 
add annotations, when the final fully annotated version of the script is 
approved by the board / panel, we could consider putting in all the names 
of those whose annotations are in the final version (those who want their 
names used).

Again, please feel free to comment on any of the above items!

TTFN,
David Merchant

Head, Systems Dept, Louisiana Tech University
merchant at latech.edu
JavaScript List Administrator (www.mountaindragon.com/javascript/)
Webmaster, HTML Encyclopedia (www.mountaindragon.com/html/)
Webmaster, Memorial Day Page: (www.usmemorialday.org/)