Design spec for Spectator tool

Version 1.0
Date 23rd Dec 02
Author Jeya Balaji [email protected]



Content

  1. Aim
  2. Functionality
  3. Technology
  4. Design
  5. Issues
  6. Future enhancements



Aim

To provide a useful utility for reviewing specs and other docs.


Functionality

Spectator utility facilitates html authors to insert fields for collecting reviews. This will be useful for floating the specs (like functional, design, test specs or any document) and getting feedback.

While writing spec (in html), the author adds special tags through out the doc (where ever the author expects comments). This tag provides facility for others to punch their comments. All the viewer comments get collected and the author can summarize that idea to prepare next version of the spec.


For eg, if you have some comments about this document, it will be convenient to have a textarea like this :




Technology




Design

A rough sketch of the usage is given here. 

<body>
	<%@taglib uri=...  prefix="spectator">

	<spectator:prepareSpectator attr >
		...
	
		<spectator:acceptComment attr />
		...
		<spectator:acceptComment attr />
		...
		
	</spectator:prepareSpectator>
	
		...
		
</body>
The <prepareSpectator> tag acts as a frame for the inner tags. The outer tag prompts (generates text field) for the reviewer to enter his/her name. Also all the initialization are done here.

The </prepareSpectator> tag closes the frame and generate code to display a submit button to save all the comments entered by the user.

The inner tag, <acceptComment>, places a text area for user input. Each of these tags gets comments pertaining to that portion of the document. These tags needs to be uniquely identified; so, an attribute name is expected. This name value should be unique among all the <acceptComment> tags of this document.

Along with the text area, this tag displays available comments for this portion (which might be entered by other reviewers).

The following optional attributes are available for the outer and inner tags.

Attribute Name Allowed values Description
name Single word Expected in <acceptComment> tag. This value is used to uniquely identify this particular tag.
inlineReviews true (default)
false		 Either display the reviews in the same document, or provide a link and display the reviews in separate page.
inlineAccept true (default)
false		 Provide the text area (for reviewer to input comments) either document, or provide a link and accept reviews in separate page.
bgColor #hhhhhh Background color in which the reviews are displayed.
fgColor #hhhhhh Foreground color in which the reviews are displayed.



Ways to tune these parameters

Once the reviewer presses submit button, the comments are stored in a xml document. This doc is retrived later thru a xsl to display the comments.

The xml format is as follows : 


<reviews>
	<review>
		<name>MultiThreadSync</name>
		<comment>
			<author>[email protected]</author>
			<machineId>134.92.38.183</machineId>
			<date>23.Dec.02</date>
			<message>This is great.  Need some change.
			</message>
		</comment>
		<comment>
			<author>[email protected]</author>
			<machineId>123.42.28.101</machineId>
			<date>21.Dec.02</date>
			<message>Can u change int j?
			</message>
		</comment>
	</review>
	
	<review>
		<name>LinearSearch</name>
		<comment>
			<author>Elango KR</author>
			<machineId>176.23.34.752</machineId>
			<date>25.Dec.02</date>
			<message>Why dont we try binary?
			</message>
		</comment>
	</review>
</reviews>




Issues





Future enhancements

Hosted by www.Geocities.ws

1