Table of Contents · Previous · Read and Write Comments · Next
Glossary
· References ·
Reading This Document
Chapter 4 --- The Tools of the Research
Web
The tools discussed in this section are all software that the team may
use in its daily work of the RW. The tools were appropriated from
commercial or academic sources, where available and suitable; but the core
tools were built by the author specifically for the
Research Web. Frequently inadequate tools must be used out
of necessity, due to limited resources, temporal and financial. No tool is
perfect and no RW is static in its needs, so tools must be revised or new
tools acquired in order to support the team.
Tools must meet several standards in order to be useful:
- The tools should be familiar to operate, or transparent
(Ruhleder and King 1991, 352).
Difficult tools will be avoided by the team members, and will severely
degrade the effectivity of the RW.
- The tools should support a known or appropriated
communication genre.
- The tools should be priced reasonably.
- The tools should be maintainable by the
facilitator.
4.1 E-Mail 
Email is the universal communications tool. It is a genre that is
adopted from the familiar office memorandum
(Orlikowski and Yates 1994, 555). The genre is very highly augmented
in the Internet environment, including numerous very useful features such
as hypertext links to web pages, personal message archiving systems and
the ability to transmit files attached to the message. E-mail programs are
abundant, reliable and employer or ISP provided, or free. The team members
may use the program of their choice. In the RW e-mail is used for three
primary purposes: private communication, team communication, and
notification.
Private communication is frequently necessary to protect the social
functioning of the team. Care should be taken to prevent the hiding of
information that is of potential value to the team. If matters discussed
may be of importance to the team avoid mixing in private material. Above
all, avoid the corrosive tendency to store topical information for
personal or subgroup advantage. If a private message is to be made public,
all parties to the message should be consulted.
Team communication takes the form of management announcements, topical
queries from individuals, responses to queries, perhaps requests for
opinions on a hypothesis or proposal, and many others. The originator of
messages addressed to the entire team should copy the message to the
team's e-mail address. If the sender operates from the MailRoom, this is
automatic. Notification e-mail is sent to team members when a new page is
added, an existing page is modified, or when a comment is made in a
DocReview, HyperBibliography card, or a HyperGlossary page (see What's New
§4.7). Notification lists are customized to notify only those who
wish to accept notification.
4.1.1 Searchable E-mail Archives
E-mail messages are a primary source of information for the team.
Tacit knowledge often first becomes expressed to the team through e-mail.
In order to utilize the data, information and knowledge content from this
source, all messages must be indexed for full-text searching. The ability
to examine the entire e-mail archive for messages on a single topic is a
powerful tool. The search engine must display the message headers for all
messages meeting the search query's specifications. These headers will
contain links to the full text, which should highlight the keywords in the
text.
In order to be archived, all team communication (except for
notification messages) is copied to a team e-mail address. Any team member
may also archive a private message simply by copying the message to the
team e-mail address. A computer program may be activated automatically to
reindex the archives on any schedule the team requires. Once a day
indexing is a minimal requirement.
4.1.2 MailRoom
MailRoom is a program that allows the user to send mail from a
web page. MailRoom gives the team members a single point from which
they may send public e-mail to any team members, all members or members of
authoring groups. The facilitator can set up group lists on request. All
communication through the MailRoom is copied to the team's e-mail
archive address for permanent recording. The advantage for users of
MailRoom is that they know they are archiving their communication.
They are also spared the necessity of maintaining addresses for all
members, the many authoring subgroups, and the team's listserver.
MailRoom does not offer services such as attachment of files,
blind cc, return receipt, etc that e-mail programs offer. If any of these
services are deemed necessary the sender can always revert to private
e-mail with a copy sent to the team's listserver.
4.1.3 Listserver
The RW has a team listserver that serves all members and the team's
e-mail archive address. The listserver duplicates the MailRoom's
send-to-all services, though there is no conflict between the two. The
management of the site may find some reason for making the listserver open
to a different set of people than the set of members listed in MailRoom.
The listserver should have archiving and search capability, if not then
MailRoom should be used exclusively.
Suitable listserver software with archiving and full text searching is
expensive. Research teams can take advantage of institutional
cooperation by utilizing the site license
of one of the cooperating institutions. There is no reason for the RW to
be sited at a single institution. The facilitator should have access to
the listserver in order to correct or delete messages and to edit the
address list of members.
4.2 The World Wide Web
The World-Wide Web (WWW) is both part of and the foundation of the
infrastructure of the
Research Web as
currently designed. This WWW is a peculiar foundation, however; as a
revolutionary and recent innovation it is very much a work in progress
(Berners-Lee 1999). As time passes and
more people use the WWW, the need for change exerts itself inexorably. As
changes are incorporated, they open new ways for humans to interact with
each other and with the machines that may be utilized from the WWW. The
hardware environment also changes as entrepreneurs and research labs
invent new machines that allow us to realize the powers of the web. At the
time of writing, the most common environment for web users is the personal
computer workstation plugged into the Internet with the wires and cables
offering services of varying capacity. This environment will change, just
as the WWW itself. Wireless access to the WWW will allow portable machines
to display web pages anywhere in a variety of devices. One of the most
promising devices is the wireless electronic book
(Marshall, et.al. 1999) that will
eventually offer portability, access, freehand input of annotation, and
all the power of the current PCs.
The software environment is changing even more rapidly than the
hardware environment. Currently, there are a plethora of file types that
can be read with web browsers, but most files are coded in HTML (HyperText
Markup Language). HTML is a markup language that controls how the browser
displays content. Access to databases cannot be done with HTML, but must
be done with a very complex set of software installed on the server. The
introduction of XML (eXtensible Markup Language) allows several services
to be added to the web page including access to databases and display of
very exotic notations, such as complex mathematical notation
(Bosak and Bray, 1999). Unlike HTML,
XML programming will require real computer programming ability. This fact
and the growing importance of other computer languages, like Java and
JavaScript underscore the need for a technically qualified facilitator to
manage the RW web site.
4.2.1 Browsers
There are two major browsers in use at the time of writing, Netscape
Communicator and Microsoft Internet Explorer. All web pages must be tested
for proper operation on both of these browsers. There are many other
browsers available and team members may use the browser of their own
choosing, but it should be made clear that other browsers may not work
properly. The
facilitator should design
materials to operate in browsers at least two years old
(Nielsen 2000), since some team members
might not upgrade their browsers on a regular basis. Older browsers are
generally quite capable of meeting the needs of the RW; most of the
"improvements" offered by more recent versions are market-driven features
of marginal value. Practice conservative design; just because some feature
may be used does not mean it should be used!
4.2.2 CGI Programs
Interactive behavior of web pages, such as annotation facilities,
requires the use of fill-out forms. Each form must be backed up with a
computer program called a CGI script (
Common Gateway Interface). These
scripts are computer programs written in any one of many computer
languages. The team members, except for the facilitator, are not exposed
to these programs in any way. The CGI programs can perform many functions
far beyond the capability of normal web pages. E-mail may be sent,
databases may be accessed for data manipulation and computer programs of
any complexity may be run on the server computer with a report of results
returned to the client's browser.
4.2.3 Helpers, Plug-ins, and Other Programming
Special multimedia presentations such as audio, video, motion
pictures, postscript displays, pdf displays, slide shows and others
require that the browser be augmented with special programs. These
programs are called plug-ins or helpers. Many
documents, for instance, are displayed in a
special format called PDF, display of these documents require that the
Adobe Acrobat Reader be installed in the browser. While installation of
such programs is very simple for those who have modest computer skills,
some people simply do not have the time and inclination to install
plug-ins. For this reason, the web site needs to use only the most
essential plug-ins. Detailed instructions and help with installation must
be offered to all team members when plug-ins are required.
4.2.4 Calendar
When there is a
synchronous component
to the operation of the Research Web, meetings can be set up with the use
of a web-based calendaring system. Meetings are much more effective with
an agenda, and the calendaring system allows negotiation of agenda items.
A calendar may also provide a hypertext link to minutes of meetings just
past. There are many free or inexpensive calendaring systems available the
facilitator can set one up for the team in a couple of hours. Typically
the calendar allows anyone to enter events on the system, but on an active
site, the facilitator may want to manage the entry of information.
4.2.5 Discussion Groups
One of the Internet's most well-known and used pieces of software is
the threaded discussion group
(Valdes 2000),
(Wooley 1998).
Discussion groups are likely to be a useful tool in any RW as they offer
an informal free-form discussion; however, the success of discussion
groups should not be assumed! There appears to be a critical mass effect
in discussion groups. Palme suggests that the lower limit for success is
20 to 50 active participants
(Palme 1995, 2). There is an upper limit as well, established by
excessive message traffic; but this is far beyond the likely membership of
a research team. Developing a successful topic may require leadership in
the form of gentle admonitions and occasional reminders often in the form
of questions and summaries. Discussion forums allow very general
discussions to mutate into a branching structure that is confusing to
novices. Extensive discussions frequently lead to topic spread, and even
topic loss—these shortcomings were the impetus to develop DocReview
(see §4.3). DocReview is a very highly
directed critical annotation
tool that does not encourage discussion of comments.
4.2.6 Development Tools
Composition of content for the RW's web site can use two methods:
conversion of word processor files, or direct editing in an HTML editor.
Content prepared by scholars is almost certainly done with a word
processor. The programs that convert word processor files to HTML do not
produce HTML compliant with industry specifications. The files created by
these conversion programs are bloated files full of unnecessary tags. Not
only is the quality poor, but also the code produced is not compliant with
practices designed to produce copy that can be read by visually impaired
individuals who may be more comfortable with a larger type font. One
company actually uses, as a marketing point, the fact that its product
(DreamWeaver) weeds out unnecessary tags ("trash") from MicroSoft's Word
HTML converter
(Anon 1999, 348). There
are standalone programs that do a better job of conversion than the
programs provided in the word processors. Both popular browsers have
editors that produce HTML code. Nonetheless, the code from these simple
HTML editors frequently needs to be corrected.
The tool used to correct faulty HTML is a plain text editor
(Holzschlag 2000). The advantage of a
plain text editor is that it does not produce unwanted characters, as all
word processors do. The code produced is ASCII characters. Should the
facilitator be writing programming in Java, JavaScript, or CGI programs in
Perl, such a plain text editor is essential as none of these languages
tolerate the gratuitous characters inserted by word processors.
Programs that can produce and edit digital images are necessary for all
but the simplest site. The facilitator needs a good assortment of graphic
tools in order to create diagrams for the team, to convert from one format
to another, to create "thumbnails", and to edit images. A tool to create
image maps (hot spots) for diagrams and pictures is necessary. There are
many tools in all these categories, for all budgets.
4.3 DocReview
The World-Wide Web (WWW) provides an interactive mode of operation,
CGI scripts, that allow
asynchronous
distributed
collaboration by means of
critical review of documents. DocReview is web-based software that
facilitates the review of documents by user annotation. The commentary is
permanent and immediately available to the collaborative team. In the
Research Web almost all documents are
annotatable using either DocReview or an e-mail link.
Critical annotation of documents is a practice fundamental to scholarly
activity. A product that uses a frame of reference familiar to the user's
culture is more likely to be well received
(Orlikowski 1993). DocReview is designed to provide collaborators
with a tool whose success is based on ease of use and familiarity
(Grudin 1994). A document presented for
review with DocReview becomes a
boundary object
(Star, 1989), a place in cognitive space where members of
interdisciplinary teams can come together to share their knowledge about
the document's content, and their opinions on its presentation as well.
Critical review is an activity that attracts both learners and professors,
thus DocReview also becomes a recruiting device for the collaboration, a
conscription device
(Henderson, 1991).
An annotation program must satisfy several general design requirements
to be successful. First the program has to be accessible and interactive.
Both of these requirements are met by designing the tool to operate on the
WWW. Second, the tool has to be easy to learn and use. The widely known
behavior of the WWW largely satisfies this requirement. Ease of use, which
includes learning the behavior of the tool, is aided by the tool's
simplicity. DocReview uses links sparingly: in the latest version there
are only two buttons used to go to additional services or more
information, and two linking tags which are repeatedly used for reading
and writing annotation on pre-selected segments of the document. Simple:
click "W" to write, "R" to read. Finally, the behavior has to satisfy most
annotation functions in a manner that closely follows customary
"hard-copy" annotation.
How do people annotate hard copy? The first act of annotation is to fix
the location of the comment. DocReview provides tags at convenient
locations so the reviewer can click on a link that applies to a section of
text (a paragraph or cognitive chunk), or to an embedded graphic or table
cell. Wordsmithing (minor edits) usually applies to single words or
phrases. Comments on grammar or errors in the content generally apply to
sentences or paragraphs. Occasionally entire paragraphs or sections may be
the subjects of annotation. The sponsor or editor of the DocReview must
determine the segmentation to suit the anticipated annotation behavior of
the users. Typically each paragraph is made a review segment, but the
dense sentences of some scientific works may be made into individual
review segments. Abstracts are often rich in such sentences. Often there
are comments that apply to the entire document, or simply have no
locational focus. DocReview has a dedicated area for making general
comments.
Ease of use is critical. Collaborators have only a limited amount of
cognitive energy available for the collaboration. That energy should be
focused on the content of the collaboration, not on the technical
environment and tools. The great advantage of using the WWW is its very
simple interface. Any web-based tool should be careful not to add
complexity to the environment. The tool will ideally be completely
transparent, that is, will look and behave just like any other web
page. If a reluctant user finds difficulties by having to learn a
complex user interface, then that user is not likely to participate.
The existence of a permanent record of the critical dialog is very
important to collaborators who reflect on the commentary again and again
on their way to understanding
(Kaye 1992, 17). DocReview permanently records the base document and
all commentary. After the review has served its purpose it may easily be
archived. All archived DocReviews are instantly available in read-only
format. Besides performing the necessary recording function, this
permanence encourages quality annotation. Knowing that your words are
forever on the record sharpens the mind and cools the emotions.
Notification when annotations are posted is very important. DocReview
has a feature which allows participants to request notification when
comments are made on any particular DocReview. This feature is not only a
service to the requester, but also acts as a stimulus to the collaboration
itself since the notification messages tend to generate further
participation from the requester. It is possible for a sponsor to sign up
the entire research team on a mailing list for notification. The
notification messages are designed to discourage off-the-record direct
e-mail replies, so the requester must return to the DocReview in order to
respond.
Collaboration must be encouraged at every opportunity. The knowledge
that your participation or lack of collaboration is a matter of public
record is a powerful incentive
(Gächer and Fehr 1999). When the sponsor of the DocReview sends out an
e-mail announcement of the review, everyone on the mailing list receiving
the announcement knows who was invited to join the collaboration. Any
social process creates its own in-group. If someone consistently fails to
participate, they are soon perceived to be outside the group.
Non-participants are unlikely to be included in any credits for the work.
Collaborators are psychologically motivated by many factors, not the
least of which is vanity. We all want our colleagues to know that we are
hard at work on the products of the collaboration. In addition to vanity
there are mass and threshold effects. These effects suggest that social
activity indicators should be included in any software intended for group
use
(Ackerman and Starr 1996).
DocReview displays a message in its 'header' that tells the readers how
many comments have been received, who the latest contributor was, and when
the annotation was made. The sponsor of the review can often stimulate
lagging participation by injecting a comment to "get things moving."
One of the strengths of asynchronous communication is its
reflective nature. Recognizing the need for
researchers to reflect on what they've read, and that the user's
environment does not always include a computer connected to the WWW,
DocReview provides a display option provided that inserts annotations into
the document just below the appropriate review segment. This display, the
"on-the-plane DocReview," can be printed, enabling the traveler to reflect
on the document and its annotations while away from the office.
Handwritten marginal notes can be keyed into the DocReview when the
traveler returns to the Internet. DocReview soon may be enhanced to allow
downloading a DocReview into a Palm Pilot, allowing comments to be
uploaded to the server when the user returns to an office workstation.
Providing easy navigation to the services offered by the tool
encourages use of any tool. All services beyond the basic commentary
facility may be accessed in any DocReview by clicking a button marked
"Special Features." An active collaboration may have many DocReviews in
use at the same time. An index, which operates from a pull-down menu of
active DocReviews, encourages navigation to any review at a click. A
"What's New" feature provides the user with an itemized list of activity
in any or all DocReviews on the site since any given date. Readers can get
a complete activity log for the entire site by leaving the date open and
selecting "All" from a pull-down menu of active DocReviews. The editor can
see from the activity log who is contributing, and who isn't.
Users employing HTML in their commentary, or who cut and paste comments
into the DocReview may use a preview feature to review the comment for
typographical errors. After receiving the comment, as a polite gesture,
DocReview thanks the contributor for each comment and offers to display
all the comments made in the review segment just commented on.
Notification of annotation to those who wished to be notified of changes
is e-mailed by DocReview. The DocReview itself is updated immediately.
4.3.1 Universal Commenting Facility
In large research projects findings are often reported in essays or
monographs. Position papers are frequently produced to clarify views on a
topic. All these web documents, while finished, are, in a collaborative
environment, always contingent and open to revision, correction, and
qualification. DocReview has the ability to display the base document
without review segment tags, the instruction headers and copyright notice.
We can use this ability to give the editor the ability to present
documents in plain form, but to offer the ability to comment on this same
plain text. Clicking a “Read and Write Comments” link at the
head of the page enables commenting. If you click that link the document
is displayed on a new window in DocReview format ready for commenting.
Each document then has a universal commenting facility.
4.3.2 Applying DocReview to Documents
Thought provoking messages or memoranda can be distributed on the WWW
as DocReviews just as easily as through e-mail. The collaboration
facilitator or other skilled staff member
can manage the extra work of converting the memo to HTML. If cast in
DocReview, all readers may comment on a common copy rather than engaging
in a blizzard of repetitive and hard to follow e-mail replies (often not
addressed to all recipients).
Specifications are documents that move interested parties toward the
completion of a common task. Specifying the design and planning the
completion of any large product is a rational and prudent action in any
group activity. Several types of tasks are sufficiently complex to warrant
description and design by specification: large documents, WWW sites, and
software. Presentation of information on a large scale requires
consideration of goals and means, audience, resources, information content
and presentation. These requirements are quite similar in both text and
hypertext. Software specifications are central to the successful
production of useful programs. Both users and programmers use this common
design document. Coming to a common understanding of functions and
behavior of the software saves time and money. Having a permanent
DocReview record of the dialog provides a necessary case history of this
important phase of document or software development.
The writing task and annotation of drafts are key tasks in the final
stages of most scholarly collaborations
(Kraut, Galegher and Egido 1988). Drafts and outlines of professional
papers may be reviewed with DocReview. Papers are usually far too long to
be reviewed electronically as a single document but may easily be
fragmented along the paper's logical divisions. The DocReview of a paper
or other large work is entered through a DocReview of the Table of
Contents of the work. The organization of the document in the large can be
annotated in this DocReview, and each heading in the table can be made a
link to a DocReview of that section of the work. In other words, there can
be hypertextual organization within the DocReview itself. Collaborative
grant proposals can be handled just as papers are.
In 1997 DocReview was used in the analysis of user evaluation
questionnaires about an information collection and dissemination system.
The questionnaire was presented on the WWW as a form with several
free-form text inputs. Eight responses were received. These responses were
blinded and redisplayed in DocReview to allow an analysis team to
deconstruct the responses of each responder to determine what was causing
the problems (or successes). These DocReviews were then used to create a
document that summarized the analyses of the responses, question by
question, and then recommended corrections to the design and presentation
of the system. The recommendation document was itself mounted in DocReview
to allow comments to be made on the recommendations. After the end of the
review period and negotiations with the commenter, a report was issued
detailing the changes to be made. The report was given to the software
developers for implementation and letters were sent to the responders
thanking them for their participation and detailing the changes made or
not made in response to their comments.
While DocReview is an easy program to use, the work of the editor
requires a modest knowledge of the server computer's operating system
(UNIX) and HTML. Setting up the review segments in the base document
requires some learning and practice. Furthermore there are some finer
points of DocReview that are rarely used by an infrequent (or busy)
editor. These skills are often not required in many of the collaborator's
professional environment. We have found it almost imperative to have a
technical person (collaboration facilitator) assigned to act as the editor
for the entire team. The collaboration facilitator is called on often
enough to stay "fresh" and on becoming familiar, by use, with the fine
points can produce more effective DocReview installations.
4.3.2.1 Conversion of the Base Document
The document to be reviewed must first be converted to HTML. If the
document was written in a WYSIWYG HTML editor such as Netscape Composer,
then few if any modifications are necessary. Documents written in plain
ASCII text may be converted to HTML manually or by first converting the to
word processor files. Documents that are prepared in word processors may
be converted to HTML with a converter provider in the word processor. The
converted file is likely to contain many unnecessary tags that should be
removed for clarity, compactness, and robustness. Dreamweaver makes a
product that will clean up Word conversions
(Anon 1999, 346). The facilitator will act as editor for the
mounting of DocReviews, so must be familiar with HTML and converters.
4.3.2.2 Tagging the Base Document
The base document HTML must now be tagged to identify the "review
segments." A complete set of tagging instructions is available in the
DocReview Editor's Guide. Review segments are sections of the document
that may be individually annotated. There are two ways to tag review
segments: use of existing HTML tags, or insertion of "special tags." For
simple documents, a checkoff list may be used to select any or all of
these elements to be designated as review segments: paragraphs, list
elements, tables, and table cells. For more complex documents, using the
"supplemental" special tag may also be used. The supplemental tag is a
user-defined tag, defaulted to <rs> that will designate review
segments. The supplemental tag is simply inserted wherever the editor
wants to start a review segment. All review segments end at the start of
the next review segment.
Other tags that may be used to make the review segments better defined
are the "no tag" (<notag>) tag and "segment end" (<endseg> or
<segend>) tags. The segment end tags are used to specify the ending
of a review segment before the beginning of the next one. This is commonly
encountered when the editor wants to leave section headings or quotations
outside the review segment. The notag tag is used when the editor is using
existing tags for review segments and wishes to declare that a particular
review segment tag is to be disregarded. This allows a single review
segment to include more than one paragraph or list element.
4.3.3 Managing the DocReviews
The management of the DocReview is done through a set of HTML form
pages that may be called up from the "Managing the DocReviews" page. This
page allows the editor to select, by button click, which of four
operations (Create, Archive, Delete, Remove Comment) is to be performed.
4.3.3.1 Creating the DocReview
Once the base document has been converted and tagged, the creation of
the DocReview is managed by filling out a form selected from the "Managing
the DocReviews" page. The creation form contains many options that are
explained through hypertext links from the form page.
Fields that
must be filled out are:
- HTML file name (the file name for the marked base document)
The file must be located on the server where the DocReview programs
can open it.
- Review title (a short name for the review)
In several places the DocReview program inserts a title for the
DocReview. The purpose of the title is to differentiate between DocReviews
in the index of DocReviews, not to describe the document under review. The
length of the DocReview title is limited to sixty characters.
- Review Nickname (the name of the directory for DocReview
files)
All the files for each document installation are kept in a single
subdirectory. This directory needs to have a directory name for the
URL that accesses the DocReview installation. The
directory name has to be a unique legal directory name. In the case of
UNIX machines this means some combination of upper and lower case letters,
digits, and the underscore character. The program checks for this, so if
your operating system accepts other characters, don't use them.
The
DocReview "nickname" must be relative to the DocReview directory. Suppose
you would like to create the nickname directory on the same level as the
DocReview directory; in that case you should enter ".../Nickname" in the
form. If the nickname directory is to be within the DocReview directory,
then "Nickname" should be entered in the form.
- Sponsor's Name (usually the author of the document)
When the user submits a comment, the program sends an acknowledgment
message. The sponsor's name is appended to the acknowledgment as a
signature. If you wish to append a facsimile of your signature
automatically to all acknowledgments, all you need to do is to create a
scanned image of your signature and store it as "sig.gif" in the directory
immediately above the DocReview directory.
If the editor accepts the standard default selections for the remaining
fields, the DocReview may now be created by clicking the "CREATE DocReview
INSTALLATION" button. But if the defaults need to be overridden, then the
proper values may be entered in the fields provided for:
- Review tags (default paragraphs and list elements)
You may check off any or all of these elements to become review
segments: paragraphs, list elements, tables and table cells.
- Replacement review tag (default <rs>)
The replacement review tag is simply a user-devised review tag that
you may insert into the base document. You might make the tag <RS>,
<FAKE>, <REPL> or any other non-standard HTML tag. You might
need to place a review tag at a graphic, or at the document title. The
replacement review tag allows you place a review tag anywhere in the
document.
- General Comments Allowed (default yes)
Review segments allow the user to comment on a short section of the
document, but frequently the user will want to comment on the entire
document. This commentary may refer to the absence of some information,
the general tone of the document, or perhaps even some general praise!
Some documents may have special instructions such as a request for
approval/disapproval, voting, a request for permanent annotations for an
enterprise-wide annotated bibliography, or suggestions for entries in a
glossary. The general comments section provides a place for special
remarks. To add a general comments segment, accept the default (checked).
- Suppress bolding of comments in the comment pages (default no)
When the user clicks on the W tag of a review segment, the program
pops up a page with a form to enter the commentary. In order to remind the
user what is being criticized, the text of the review segment is written
above the field for the comment. This text is normally presented in the
bolded italic face. To eliminate this emphasis, accept the default value
(checked).
Materials that benefit from eliminating the emphasis are review
materials that contain bold face or italic text that provides meaning.
Bibliographic materials are an example of material that projects meaning
through typeface. Suppressing the program's emphasis allows the HTML tags
for this material to function properly.
- Log comment authors and their address (default yes)
In order to automatically fill in the user's name and e-mail address
in the comment form, DocReview's comment filing script creates cookies.
These same cookies are also used to log the user's annotations in the log
file (log.txt). If you check off this box, reading sessions will be logged
using the cookie data, if not, the reading sessions will be logged
anonymously. There is an ethical issue for you to decide. If you choose to
log the reader's name and e-mail address do you need to inform the reader
beforehand? Do you know all the readers?
- Color of DocReview tags (default FF6508 -- orange)
There are color accents throughout the DocReview pages, usually in the
titles. If you don't care for the Insignia Orange color accent of the
default setting you can change it by entering a six character hexadecimal
code RRGGBB: where RR is the saturation of the red,
GG is the green, and BB the blue.
- Special Instructions to users (default blank)
For most text documents the simple instructions in the header on how
to read and write are sufficient. Special instructions might be in order
for some documents. There might be a deadline for participation, say to
reviewing meeting minutes that are to be published on a fixed schedule.
Documents that accumulate new data in addition to commentary on existing
data may refer the user to the general comments area to suggest new
materials for the collection. You may use HTML in this field to provide
emphasis, lists, or links.
- Restrict writing of comments (default no)
You may wish to restrict the ability to contribute comments to a
select group, while leaving the review open for reading. If, for instance,
you are reviewing a controversial document, open public commenting may
dilute the comments of your reviewers or attract graffiti. If you wish to
restrict both reading and writing, then simply use the .htaccess and
.htpasswd methods of protection common to UNIX machines.
If you wish to restrict writing, enter a password of your choosing on
this line. It is effective for this single document review. It is best to
keep it short and in lower case. Be sure to notify your reviewers of the
password. This can be done at the same time you announce the installation
of the document for review.
- List of people to notify of comments (default blank)
If you are, as either a user or editor, involved in several reviews,
it is quite burdensome to have to scan every DocReview installation to see
if any comments have been made since last seen. DocReview can issue e-mail
notification as comments are entered.
To notify someone, just enter the e-mail address(es) in the field
provided. Separate the addresses by comma. Use no spaces! Addresses must
be legally formatted, but the program cannot check to see if the legal
addresses actually point to the right person. You may add names on this
list, and add everyone on a separate list (see next item).
- File name of comment notification list (default notificationlist.txt)
To notify an entire list of people you must create a file of comma
separated addresses. Use no spaces! Addresses must be legally formatted
and correct because the program cannot check to see if the addresses
actually point to the right person. Enter the file name (relative to the
DocReview directory) in the form. The default file name is
notificationlist.txt. You may add the names on this list, and add separate
addresses (see item above). If notificationlist.txt is empty or
nonexistent, no notifications are issued.
- Name of directory for commonly used graphics (default .../graphics)
In order for graphics to appear in the DocReview, the graphic files
must appear in the nickname directory, which is created when you create
the DocReview installation. Many graphics are used in several html pages
and DocReviews. If you have copied every one of the commonly used graphic
files into a single directory, the installation program will automatically
create links from the nickname file to the common graphics directory.
Specify the common graphics directory by entering the relative path from
the DocReview directory to the common graphics directory. For example, if
the common graphics directory is at the same level as the DocReview
directory, and it is named "graphics" enter ".../graphics" in the input
box.
After the form is filled out, the "CREATE DocReview INSTALLATION button
is clicked and the computer creates the directory for the DocReview,
creates the necessary files, and updates the list of active DocReviews. If
there is a problem encountered, the computer sends back an explanation of
what is wrong without making any changes to the files on the computer. The
errors encountered are usually errors made by the editor in tagging, or
providing a "nickname" directory that is illegal, or already exists. If
the DocReview was successfully created, then the editor should carefully
review the results to see if the tagging produced the desired review tag
segmentation. If not, delete the DocReview and start over. If everything
is OK, then announce that the DocReview is open to the team members.
4.3.3.2 Deleting a DocReview
Often a DocReview is prepared incorrectly and, on review, it is
decided to correct the errors and reissue the DocReview. On other
occasions, a DocReview that has served its purpose and does not need to be
archived needs to be deleted. When a DocReview is created, there are
several actions taken that need to be undone; directories and files need
to be deleted, and other files need to have entries removed. There are so
many small items to be done that there is a program in DocReview in order
to automatically take care of deletions.
Deletion of a DocReview is managed by filling out a form that is
presented when "Delete a DocReview" is selected from the "Managing the
DocReviews" page. The deletion form asks the editor to select the name of
the DocReview to be deleted from a list of all active DocReviews. When the
editor clicks the "Delete the DocReview" button a verification page pops
up with the directory name as well as the DocReview name and asks the
editor to verify the deletion operation. If the "Yes" button is clicked,
all traces of the DocReview are removed from the system.
4.3.3.3 Archiving a DocReview
The normal operation of the document refinement process leads the
document through a sequence of edit/annotate/revise cycles. Before
document revision, the DocReview of the current version must be archived
in order to preserve the old version and all the annotations on it. In
this way a complete revision record is maintained of every document.
DocReview allows the archived versions and their annotations to be read,
but not revised or added to.
A DocReview may be archived by filling out a form that is presented
after "Archive a DocReview" is selected from the "Managing the DocReviews"
page. The form asks the editor to select the name of the DocReview to be
archived from a list of all active DocReviews. The archiving form contains
many options that are explained through hypertext links from the form
page. Fields that must be filled out are:
- the nickname for the archive.
All the files for the archives are all kept in a single subdirectory.
This directory needs to have a legal directory name for the
URL that accesses the archive. In the case of UNIX
machines this means some combination of upper and lower case letters
(a-z), digits, and the underscore character. The program checks for this,
so if your operating system accepts other characters, don't use them. An
archives "nickname" must be relative to the DocReview/archives directory.
- the title of the archived DocReview
When a DocReview Installation is archived, an index page is updated.
The entry in the index page contains a title, which is set up as a link
tag.
- a description of the archived DocReview
When a DocReview Installation is archived, an index page is updated.
The entry in the index page contains a description that informs the user
of the contents.
4.3.3.4 Deleting an Annotation
From time-to-time it becomes necessary to remove a single annotation
from the record of an active DocReview. When an annotation is submitted,
several actions are taken, all of which must be undone to properly expunge
the annotation. An annotation may be expunged by filling out the form that
is presented when the “Delete a Comment” button is clicked on
the “Managing a DocReview” page. The form requests the
following information:
The form asks the editor to select the DocReview from a list of active
DocReviews.
- the number of the review segment
The number of the review segment may be read from the filename of the
annotation file for the review segment (the nn of
pointnn.html).
- the number of the annotation within the review segment
The number of the annotation may be read from the annotation file.
4.4 The Annotated HyperBibliography
The Annotated HyperBibliography (AHB) is the tool that manages the
references for all the literature used in the
Research Web (RW). The primary functions are: to display
bibliographic information by clicking citations in
RW Essays; to display abstracts of the works;
to display full text of the work where available; and to provide a place
for research team comments on the work. The AHB is an important component
of the Research Web Essay (see
§3.4),
providing a link to several increasingly detailed representations of the
cited literature. If it were used in electronic journals, this facility
would provide a way that "classical citation behavior may reach a much
higher level of activity ..."
(van Raan 1997,447).
The AHB is a suite of programs and web pages. A personal bibliographic
manager (PBM), for example ProCite or EndNote, must be available on the
facilitator's workstation. The PBM contains the basic bibliographic
information for the AHB, all the bibliographic fields, abstract, URL for
full text, and an identifying key. The PBM must have a "style template"
installed that will translate the PBM data into an interface file that the
AHB server software uses to display the information on web pages. There is
a suite of management tools that accomplishes the conversion of the
interface file into web pages. The only "manual" editing of files that may
be required is the excision of inappropriate annotation.
4.4.1 Preparing the Bibliography
Bibliographic information is entered in the PBM largely just as one
would for a conventional bibliography. The exceptions are to add a unique
ten digit identifying key in one of the fields (usually the time of data
entry in yymmddhhmm format is added to the ISBN or ISSN field); and to add
the
URL for full text if available (a seldom used
field is usually appropriated). The fields used are at the facilitator's
option. The "style template" will need to reflect the choices made. Any
corrections to the AHB's bibliographic information are made in the PBM.
4.4.2 The Interface File
The interface file is produced using a PBM command to write a
bibliography using the "style template". The style template is a
modification of a copy of the file that produces the bibliographic format
selected, for example Chicago B or APA. The style template causes a text
file to be produced that contains not only the correct bibliographic
format in HTML, but also keywords that the AHB's management software
recognizes. Here is an example of one record of an interface file:
*key*9803031043
*biblioentry*Agre, Phil. 1998. Designing genres for new media: Social, economic
and political contexts. In <I>CyberSociety 2.0: Revisiting CMC and Community</I>.
Editor Steve Jones. Sage.
*abstract*This Chapter is a revised version of a manifesto for a course on
conceptual design for a new media, taught to communication undergraduates at
the University of California, San Diego from 1996 through 1998.
*URL*http://dlis.gseis.ucla.edu/people/pagre/genre.html
*author*Agre, Phil 1998
*title*Designing genres for new media: Social, economic and political contexts
*EOR*
Figure I An Interface File Record
4.4.3 Creating, Updating and Maintaining the AHB
Once the interface file has been created for the latest version of the
AHB, the interface file must be transferred from the workstation to the
web server. The management software of the AHB is then used to either
create or update the AHB. The creation and updating programs are run from
the WWW by clicking a button on the "Managing the Annotated
HyperBibliography" web page. A form will be displayed for the facilitator
to enter the necessary information, the name of the interface file and the
directory of the AHB. After clicking "Submit" no further action is
required. The management programs create or update the "catalog cards" and
the author index and title index. The only maintenance tasks performed on
the server are the occasional correction of an annotation, or the excision
of inappropriate annotation. Correction of the bibliographic information
is performed on the facilitator's PBM.
4.4.4 Uses for the AHB
The principal use for the AHB is to support bibliographic annotation
of the
Research Web Essays. The user
of the essay can with a click pull up the bibliographic information for a
citation. The popup window displaying that information has a button that
will bring up a "catalog card." The catalog card provides the user with an
abstract of the work (if present) and offers buttons to view full text (if
on the WWW), and gives the user the opportunity to annotate the reference.
The AHB also provides the EssayAssistant program with the information used
to automatically build the references section for the RW Essay.
The annotation feature of the AHB is what sets it apart from static
bibliographies.
Criticism is a sharp
intellectual tool that can perform several functions, many of them quality
related. Errors or omissions may be noted. Interesting ideas can be
highlighted. If a reference is superseded or challenged by new work, then
that work may be linked directly from the annotation. Works that form the
foundation of the team's research may be identified. Relationships between
references may be established. Annotation allows the research team to add
value to the references of the enterprise.
4.5 The Annotated HyperGlossary
The Annotated HyperGlossary (AHG) is a tool that allows the research
team to document the language of the research enterprise. In an
interdisciplinary research team, the vocabulary may contain terms that
have substantially different meanings. The AHG allows not only the entry
of definitions and alternate definitions, but technical glosses as well.
The definitions are each contained in a web page that may be displayed at
the click of a marked term within a document, usually a
RW essay. The entire AHG may be displayed on
the WWW. Each term and alternate definition may be annotated or glossed by
any team member.
The AHG is a suite of programs and web pages located on the server.
There is a program that allows insertion of a new term by filling out a
form on the WWW. Every time a new definition is added the Annotated
HyperGlossary web page is regenerated with the new material included in
the proper place. Access to this program is usually restricted because the
definitions and glosses usually contain cross-references to other terms,
and cross-referencing requires some minor programming by the
facilitator. When a definition is
displayed, there is a button that may be clicked to bring up an annotation
form. Annotations are displayed on the definition page. Should any
annotation, gloss, or definition need to be revised, the facilitator must
perform the editing as the text is contained on the server machine.
4.6 The EssayAssistant
The EssayAssistant is a tool that enables the author or
facilitator to insert specialized popup windows into HyperDocuments,
principally
Research Web Essays.
Displayed by a single click, these popup windows allow the reader to
obtain additional information about the content of the document without
leaving the HyperDocument. The windows may contain footnotes, sidebars,
bibliographic information, glossary definitions, or simple notes. These
features constitute the
scholarly apparatus of the Research Web Essays, and
they are complemented with the critical apparatus provided by DocReview.
In order to create these popup windows, "poptags"— HTML-like tags,
must be inserted into the base document.
The base document is then processed by a computer program, poptags.pl,
that automatically converts the poptags into the much more complex
JavaScript code. The program produces an output HTML file which contains
all the HTML tags and scripts required to make the output file pop up the
windows containing your information. The program also inserts, after the
text, appendices for references, notes and definitions, all with return
links. These insertions make the document read well in hardcopy where the
user cannot pop up windows. As a matter of course, this HTML file is
provided with a link to a DocReview of itself. This gives each
HyperDocument a built-in critical apparatus.
4.7 What's New?
A distributed work group needs powerful tools to stay "glued
together." One of the principal needs is to be informed about the group's
activities, or "What's New?" What's New essentially allows anyone to
receive a list of notification messages that were sent to members at the
time of accession or document revision. As currently implemented
What'sNew? only provides information on DocReviews. It needs to be
expanded to include new documents, document revisions, comments on
Annotated HyperBibliograpy (AHB) references, comments on Annotated
HyperGlossary (AHG) definitions, and perhaps new entries in the AHB and
AHG. When completely implemented, there will be a checkoff list for types
of documents to be listed. Eventually, What'sNew? may be augmented
with a program running in background on all team members’ computers.
This sort of background program could instantly inform the member of any
activity as it happens: rather than seeing or hearing "You've got mail,"
you might see "New RW activity."
Notifications not only inform, but also remind members that there is
work to do. These notifications, which are without cost to the
contributor, are expected to increase access to the content of the RW
(Markus 1987, 502) and thus
participation. Xerox provides e-mail notification to changes in its
Web-based repositories, including
URLs rather than
attachments
(Rein, McCue and Slein 1997, 84).
What'sNew? presents the user with a form that asks for a
beginning date for notifications. For instance the user may as for all
comments on all DocReviews or a selected DocReview from some date forward.
If no date is provided, the program will present a complete page showing
the selected activity since project inception. This page will present
transactions (creation/acquisition, commentary, archiving) chronologically
and will have clickable links to the comments, archives, or current
document.
4.8 Lexicon
The language of discourse for the
Research Web must be well defined, especially in a
multidisciplinary team. Lexicon is a tool designed to tease out the
terms used by every discipline associated with the issue domain. The basic
idea is very simple; a set of carefully central terms is defined and
entered into the tool. Each of these definitions is then opened to
criticism, and a request is made to identify
and define terms associated with the parent term. Each of these new terms
becomes a parent term of a new subhierarchy. Since a parent may suggest
many terms, only a few steps can produce a very large number of terms. The
lexicon of the
issue domain is then fairly
well established and can be moved to the more formal alphabetically
ordered Annotated HyperGlossary where it can be further refined.
"There is a strong sense that the encyclopedic method,
grouping words by themes, meets far more efficiently the need to see links
and method amid the chaos of existence."
The purpose of Lexicon is to convert the mental lexicon of the
participant into a glossary that can be shared with other participants.
The process of reflection and explaining helps the participant sharpen the
internal personal meaning of the term. The existence of multiple meanings
and nuances helps to explain the existence and causes of misunderstanding
among colleagues.
Lexicon is organized in a hierarchical manner. The start of the
lexicon is a set of contributed terms that are hopefully the major root
words of the vocabulary of the issue domain. Each of these terms is then
presented on a page that allows for discussion of the proposed definition.
Every entry page can also propose subtopics which are presented on their
own page. This process can extend without limit to finer and finer
distinctions.
This sort of organization follows the lead of P.M. Roget who, in 1852,
with his sons created one of the indispensable references for the English
language, Roget's Thesaurus
(Roget 1997). Roget took as his issue domain all the words of
the English language. His initial categories were only six: Abstract
Relations, Space, Material World, Intellect, Volition, and Sentiment and
Moral Powers. The Fourth Edition, published in 1977, includes eight
initial categories: Abstract Relations, Space, Physics, Matter, Sensation,
Intellect, Volition, and Affections. A brief look at the Thesaurus will
show its hierarchical organization.
The multiple and nuanced meanings of the terms are explained and
debated in the commentary on each entry page. Within the lexicon, this
debate will produce variant definitions or glosses. When the lexicon is
fully matured, there is little use for the hierarchical organization ---
its purpose has been served. Thus, at some point the lexicon is closed and
the dictionary or glossary becomes the repository of the vocabulary of the
issue domain. In our environment the lexicon is converted into an
Annotated HyperGlossary.
4.9 Other Tools
The tools mentioned in this section are not ready for inclusion in the
environment, but are needed. PicReview is a tool that allows annotation of
any image. The Landscape of Reason is a tool that creates a graphic layout
of an argument. This tool will give a synoptic view of the argument
surrounding a proposition, including warrants, backing, and rebuttals.
Three tools, not further discussed, have potential for use. The IdeaMill
is a proposed brainstorming tool that incorporates features that mitigate
the production blocking of "standard" brainstorming sessions, and features
that capitalize on the advantages of
asynchronous dialog. TimeMaps
graphically describe the distribution of team members with respect to the
position of the sun in the sky, showing how our circadian habits make
synchronous communication difficult.
State-Graph is a graphic method used
to describe process behavior.
Tools appropriated by its team members will augment and evolve each
Research Web. All disciplines and most specialties have software and
conceptual tools that may contribute to the processes of
modeling, understanding, and
coordination. Geographic information
systems cross all boundaries and find applications wherever physical
distributions or differentiations are important. While this dissertation
describes Research Webs dedicated to pure research, many if not most team
efforts will likely be applied research efforts. Such RWs may need
decision-making tools including voting tools and negotiation tools.
Rather than impose structure on the [Research Web],from
the outset we want to support the evolution of its own gradations of
structure, cohesion, and hence community dynamism.
4.9.1 PicReview
PicReview is a WWW-based interactive reviewing tool that allows
the posting of an image that users can annotate by referring to regions
demarcated by the user. This tool is the graphic analog to DocReview. Any
user may define and name features or regions on the image; others wishing
to comment may then reference these features or regions. Each annotation
becomes the focus statement or question for public discussion just as if
the annotation is a DocReview review segment. A complex image may be
subdivided into separate reviewable areas or themes. Types of images that
might be reviewed are: maps, diagrams, photographs, etc.
4.9.2 The Landscape of Reason
This tool is to be designed to allow informal argumentation about
propositions or hypotheses. It is based on a technique outlined by
Toulmin, Rieke and Janik
(Toulmin, Rieke and Janik 1979) and explored by Liebow, et.al.
(Liebow, et.al. 1998). This
technique is somewhat more formal than gIBIS [now QuestMap]
(Conklin and Begeman 1989), a technique
that is slanted toward policy and decision-making.
The program builds a graphic presentation that is a map of a dialog
about a single topic. The dialog surrounding any proposition is a great
branching tree of claims, rebuttals, backing, and modal qualifiers. The
tool builds a case graphically, showing the relationships in the argument.
Much of the complexity of the argument is simplified by using hyperlinks
to move sub-arguments to new pages. The claims, rebuttals, and backing are
the findings that will come from documents such as minutes, essays,
journals and reports. The Landscape of Reason could provide a framework
for the analysis of the dialog. There is an active community of scholars
working on this problem, referred to as Computer-Supported Collaborative
Argumentation (CSCA).
Conklin, in a position paper
(Conklin 1999), reports on the difficulties that
inexperienced, or only moderately experienced, people encounter when using
QuestMap. The learning curve is steep and for that reason, I propose using
The Landscape of Reason only as a representation of the argument as
prepared by the facilitator, not as an interactive tool. Like all
representations, it will, however, be annotatable. Through annotation the
team members may point out errors in the presentation and suggest
inclusion of parts of the argument that may have been overlooked.
Table of Contents · Previous · Read and Write Comments · Next
Glossary
· References ·
Reading This Document