Premiere version : mise en route du suivi.
[auf_roundup.git] / doc / .svn / text-base / original_overview.html.svn-base
1 <!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <title>Roundup: an Issue-Tracking System for Knowledge Workers</title>
4 <link rev=made href="mailto:ping@lfw.org">
5 </head><body>
6
7 <table width="100%">
8 <tr>
9
10 <td align="left">
11 <a href="http://www.software-carpentry.com">
12 <img src="images/logo-software-carpentry-standard.png" alt="[Software Carpentry logo]" border="0">
13 </a>
14 </td>
15
16 <td align="right">
17 <table>
18 <tr><td>
19 <a href="http://www.acl.lanl.gov">
20 <img src="images/logo-acl-medium.png" alt="[ACL Logo]" border="0">
21 </a>
22 </td></tr>
23 <tr><td><hr></td></tr>
24 <tr><td>
25 <a href="http://www.codesourcery.com">
26 <img src="images/logo-codesourcery-medium.png" alt="[CodeSourcery Logo]" border="0">
27 </a>
28 </td></tr>
29 </table>
30 </td>
31
32 </tr>
33
34 <tr>
35
36 <td colspan="2"><em>
37 Copyright (c) 2000 Ka-Ping Yee.  This material may
38 be distributed only subject to the terms and conditions set forth in
39 the Software Carpentry Open Publication License, which is available at:
40 <center>
41 <a href="http://www.software-carpentry.com/openpub-license.html">http://www.software-carpentry.com/openpub-license.html</a>
42 </center>
43 </em></td>
44
45 </tr>
46 </table>
47
48 <p><hr><p>
49
50
51 <h1 align=center>Roundup</h1>
52 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h3>
53 <h4 align=center>Ka-Ping Yee</h4>
54 <h4 align=center><a href="http://www.lfw.org/">lfw discorporated</a><br>
55 <a href="mailto:ping@lfw.org">ping@lfw.org</a></h4>
56
57 <!-- the following line will start a comment in lynx -soft_dquotes mode -->
58 <p style="><!--">
59
60 <p><hr>
61 <h2>Contents</h2>
62
63 <ul>
64 <li><a href="#overview">Overview</a>
65 <li><a href="#background">Background</a>
66     <ul>
67     <li><a href="#principles">Guiding Principles</a>
68     </ul>
69 <li><a href="#data">Data Model</a>
70     <ul>
71     <li><a href="#hyperdb">The Hyperdatabase</a>
72     <li><a href="#rationale">Rationale</a>
73     <li><a href="#roundupdb">Roundup's Hyperdatabase</a>
74     <li><a href="#schema">The Default Schema</a>
75     </ul>
76 <li><a href="#ui">User Interface</a>
77     <ul>
78     <li><a href="#discuss">Submission and Discussion (Nosy Lists)</a>
79     <li><a href="#edit">Editing (Templated UI)</a>
80     <li><a href="#browse">Browsing and Searching</a>
81     </ul>
82 <li><a href="#devplan">Development Plan</a>
83 <li><a href="#issues">Open Issues</a>
84 <li><a href="#summary">Summary</a>
85 <li><a href="#ack">Acknowledgements</a>
86 </ul>
87
88 <!-- this comment will end the comment started in lynx -soft_dquotes mode -->
89
90 <p><hr>
91 <h2><a name="overview">Overview</a></h2>
92
93 <p>We propose an issue-tracking system called
94 <em>Roundup</em>, which will manage a number of issues
95 (with properties such as "description", "priority", and so on)
96 and provide the ability to
97 (a) submit new issues,
98 (b) find and edit existing issues,
99 and
100 (c) discuss issues with other participants.
101 The system will facilitate communication
102 among the participants by managing discussions and
103 notifying interested parties when issues are edited.
104
105 <p>This design draws on experience from 
106 <a href="http://www.lfw.org/ping/roundup.html">an existing
107 implementation</a> which we will refer to
108 as "the Roundup prototype".
109 The graphical interface we have in mind will resemble
110 <a href="http://www.lfw.org/ping/roundup-1.png">
111 the main display of the prototype</a>.
112
113 <p align=center>
114 <a href="images/roundup-1.png">
115 <img src="images/roundup.png" width=358 height=205 border=0 alt=""></a>
116
117 <p><hr>
118 <h2><a name="background">Background</a></h2>
119
120 <p>A typical software project requires the management of
121 many tasks, usually distributed among several collaborators.
122 In fact, any project team
123 could use a tool for sorting out and discussing all the
124 relevant issues.  A common approach is to set up some kind
125 of "to-do" list that people can share.
126
127 <p>However, to address the overall problem we need much more
128 than just a shared to-do list; we need to
129 manage a growing body of knowledge and experience to help a
130 team collaborate effectively on a project.  The issue-tracking
131 tool becomes a nexus for communication: the Grand Central
132 Station of the group intelligence.
133
134 <p>The primary focus of this design is to help
135 developers work together well, not to provide a customer
136 service interface to the developers.  This is not to say that
137 the design is to be made unsuitable for customers to use.
138 Rather, it is assumed that many of the same qualities
139 that are good for supporting development (see below)
140 are also good for non-developers using the system.
141 Additional niceties
142 for providing a safe or simplified interface to clients are
143 intentionally deferred for later consideration.
144
145 <p>A good issue-tracking system should have at least the
146 following properties:
147
148 <p><table align=right width="40%" bgcolor="#808080"
149 cellspacing=0 cellpadding=0 border=0><tr><td
150 ><table bgcolor="#e8e8e8" width="100%"
151 cellspacing=0 cellpadding=5 border=0><tr><td
152 ><p><font color="#808080"><small>
153 With a nod to the time-honoured computer science tradition
154 of "filling in the fourth quadrant", we note that
155 there are really four kinds of information flow
156 going on here.  The three mentioned qualities
157 really address the first three quadrants of this 2-by-2 matrix,
158 respectively:
159
160 <ol>
161 <li>User push: a user submits information to the system.
162 <li>User pull: a user queries for information from the system.
163 <li>System push: the system sends information out to users.
164 <li>System pull: the system solicits information from users.
165 </ol>
166
167 An example of the fourth kind of flow is voting.
168 Voting isn't described in this design,
169 but it should be noted as a potential enhancement.
170 </small></font></td></tr></table></td></tr></table>
171
172 <ol>
173 <li><strong>Low barrier to participation.</strong>
174 The usefulness of the tool depends entirely on the
175 information people contribute to it.  It must be made
176 as easy as possible to submit new issues and contribute
177 information about existing issues.<p>
178
179 <li><strong>Straightforward navigation.</strong>
180 It should be easy for users to extract information they need
181 from the system to direct their decisions and tasks.
182 They should be able to get a decent overview of
183 things as well as finding specific information when
184 they know what they're after.<p>
185
186 <li><strong>Controlled information flow.</strong>
187 The users must have control over how much information and
188 what information they get.  A common flaw of some issue-tracking
189 systems is that they inundate users with so much useless
190 e-mail that people avoid the system altogether.
191 </ol>
192 <br clear=all>
193
194 <p><br>
195 <h3><a name="principles">Guiding Principles</a></h3>
196
197 <p><strong>Simplicity.</strong> It is a strong requirement
198 that the tool be accessible and understandable.  It should
199 be fairly obvious what different parts of the interface do,
200 and the inner mechanisms should operate in ways that most
201 users can easily predict.
202
203 <p><strong>Efficiency.</strong>
204 We aim to optimize for minimum effort to do the most common
205 operations, and best use of resources like screen real estate
206 to maximize the amount of information that we summarize and present.
207
208 <p><strong>Generality.</strong> We try to avoid making
209 unnecessary assumptions that would restrict the applicability
210 of the tool.  For example, there is no reason why one might
211 not also want to use this tool to manage a design process,
212 non-software projects, or organizational decisions.
213
214 <p><strong>Persistence.</strong> We
215 prefer hiding or reclassifying information to deleting it.
216 This helps support the collection of statistics later.
217 If records are never destroyed, there is little danger
218 in providing access to a larger community, and logging yields
219 accountability, which may encourage better behaviour.
220
221 <p><hr>
222 <p><table align=right width="40%" bgcolor="#808080"
223 cellspacing=0 cellpadding=0 border=0><tr><td
224 ><table bgcolor="#e8e8e8" width="100%"
225 cellspacing=0 cellpadding=5 border=0><tr><td
226 ><font color="#808080"><small>
227 Okay, enough ranting.  Let's get down to business.
228 </small></font></td></tr></table></td></tr></table>
229 <h2><a name="data">Data Model</a></h2>
230
231 <p>Roundup stores a number of <em>items</em>, each of
232 which can have several properties and an associated discussion.
233 The properties can be used to classify or search for items.
234 The discussion is a sequence of e-mail messages.
235 Each item is identified by a unique number, and has
236 an activity log which
237 records the time and content of edits made on its properties.
238 The log stays fairly small since the design intentionally
239 provides only small data types as item properties, and
240 encourages anything large to be attached to
241 e-mail where it becomes part of the discussion.
242 The next section explains how items are organized.
243
244 <h3><a name="hyperdb">The Hyperdatabase</a></h3>
245
246 <p><table align=right width="40%" bgcolor="#808080"
247 cellspacing=0 cellpadding=0 border=0><tr><td
248 ><table bgcolor="#e8e8e8" width="100%"
249 cellspacing=0 cellpadding=5 border=0><tr><td
250 ><font color="#808080"><small>
251 In my opinion, forcing
252 items into fixed categories is one of the most
253 serious problems with the Roundup prototype.
254 The hyperdatabase is an <em>experimental</em> attempt to
255 address the problem of information organization,
256 whose scope goes beyond just Roundup.
257 </small></font></td></tr></table></td></tr></table>
258
259 Often when classifying information we are
260 asked to select exactly one of a number of categories
261 or to fit it into a rigid hierarchy.  Yet things
262 only sometimes fall into one category; often,
263 a piece of information may be related to several concepts.
264
265 For example, forcing each item into a single topic
266 category is not just suboptimal but counterproductive:
267 seekers of that
268 item may expect to find it in a different category
269 and conclude that the item is not present in the
270 database -- which has them <em>worse</em> off
271 than if the items were not categorized at all.
272
273 <p>Some systems try to alleviate this problem by
274 allowing nodes to appear at multiple locations
275 in a tree, as with "aliases" or "symbolic links" in
276 a filesystem, for example.  This does help somewhat,
277 but we want to be even more flexible
278 by allowing the
279 organization of nodes into sets that may freely
280 intersect.  Rather than putting each node at exactly
281 one place in an overall "grand scheme", a node can
282 belong to as many sets as are appropriate.
283
284 If we choose to represent the sets themselves as nodes
285 and set membership as a link between nodes,
286 we're now ready to present the definition of a
287 hyperdatabase.
288
289 <p><table align=right width="40%" bgcolor="#808080"
290 cellpadding=0 cellspacing=0 border=0><tr><td
291 ><table bgcolor="#e8e8e8" width="100%"
292 cellspacing=0 cellpadding=5 border=0><tr><td
293 ><font color="#808080"><small>
294 Perhaps it's too pretentious a name?
295 You could say this is just like an object database.
296 The hyperdatabase is hardly much of an invention; the
297 intent is merely to emphasize querying on links
298 rather than properties.
299 (I haven't heard of this being done with
300 object databases before, but plead ignorance if
301 there's already a good name for this idea.)
302 </small></font></td></tr></table></td></tr></table>
303 A <em>hyperdatabase</em> is a collection of <em>nodes</em>
304 that may be hyperlinked to
305 each other (hence the name "hyperdatabase").
306 Each node carries a collection of key-value pairs,
307 where some of the values may be links to other nodes.
308 Any node may have an arbitrary number of outgoing and
309 incoming links.  Hyperdatabases are able to efficiently
310 answer queries such as "what nodes link to this node?"
311 and "what nodes does this node link to?"
312
313 <h3><a name="rationale">Rationale</a></h3>
314
315 <p>There are several reasons for building our
316 own kind of database for Roundup rather than using an existing one.
317
318 Requiring the installation of a full-blown third-party
319 SQL database system would probably deter many potential
320 users from attempting to set up Roundup;
321 yet a real relational database would be too
322 complicated to implement on our own.
323
324 On the other hand, a hyperdatabase can be implemented fairly easily
325 using one of the Python DBM modules, so we can
326 take the "batteries-included" approach and provide it
327 as part of the system.  It's easier to build and understand
328 than a true relational database (in accordance with our guiding
329 principle of <em>simplicity</em>), but provides
330 most of the query functionality we want.
331
332 <p>A hyperdatabase is well suited for finding the intersection
333 of a number of sets in which items belong.  We expect that
334 most of the queries people want to do will be of this
335 form, rather than complicated SQL queries.  For example, a
336 typical request might be
337 "show me all critical items related to security".
338 The ability to store arbitrary key-value pairs and links
339 on nodes gives it more flexibility than an RDBMS.
340
341 Users are not going to be making thousands of queries
342 per second, so it makes sense to optimize for simplicity
343 and flexibility rather than performance.
344
345 <p align=center><img src="images/hyperdb.png" width=433 height=352 alt=""></a>
346
347
348 <h3><a name="roundupdb">Roundup's Hyperdatabase</a></h3>
349
350 <p>For our application, we store each item as a node in a
351 hyperdatabase.  The item's properties are stored
352 as key-value pairs on its node.
353 Four types of properties are allowed:
354 <em>string</em>, <em>date</em>,
355 <em>choice</em>, and <em>reference</em>.
356
357 <p>The <em>string</em> type is for short, free-form strings.
358 String properties are not intended to contain large
359 amounts of text, and it is recommended that they be presented
360 as one-line fields to encourage brevity.
361
362 <p>The <em>date</em> type is for calendar dates and times.
363
364 <p>The <em>choice</em> type denotes a single selection
365 from a number of options.  A <em>choice</em> property
366 entails a link from the node possessing the property to
367 the node representing the chosen option.
368
369 <p>The <em>reference</em> type is for a list of links to any
370 number of other nodes in the in the database.  A <em>reference</em>
371 property, for example, can be used to refer to related items
372 or topic categories relevant to an item.
373
374 <p>For Roundup, all items have five properties
375 that are not customizable:
376
377 <ul>
378 <li>a <em>string</em> property named <strong>description</strong>
379 <li>a <em>reference</em> property named <strong>superseder</strong>
380 <li>a <em>reference</em> property named <strong>nosy</strong>
381 <li>a <em>date</em> property named <strong>creation</strong>
382 <li>a <em>date</em> property named <strong>activity</strong>
383 </ul>
384
385 <p>The <strong>description</strong> property is a short
386 one-line description of the item.
387 The detailed description can go in the
388 first e-mail message of the item's discussion spool.
389
390 <p>The <strong>superseder</strong> property is used to 
391 support the splitting, joining, or replacing of items.
392 When several items need to be
393 joined into a single item, all the old items
394 link to the new item in their <strong>superseder</strong>
395 property.
396 When an item needs to be split apart, the item
397 references all the new items in its <strong>superseder</strong>
398 propety.
399 We can easily list all active items just by checking
400 for an empty <strong>superseder</strong> property, and trace
401 the path of an item's origins by querying the hyperdatabase
402 for links.
403
404 <p>The <strong>nosy</strong> property contains a list of
405 the people who are interested in an item.  This
406 mechanism is explained in
407 <a href="#discuss">the section on Nosy Lists</a>.
408
409 <p>The <strong>creation</strong> property records the
410 item's creation time.  The <strong>activity</strong>
411 property records the last time that the item was edited or
412 a mail message was added to its discussion spool.  These two
413 properties are managed by Roundup and are not available to
414 be edited like other properties.
415
416 <p>Users of the system are also represented by nodes in the
417 hyperdatabase, containing properties
418 like the user's e-mail address, login name, and password.
419
420 <h3><a name="schema">The Default Schema</a></h3>
421
422 <p><table align=right width="40%" bgcolor="#808080"
423 cellpadding=0 cellspacing=0 border=0><tr><td
424 ><table bgcolor="#e8e8e8" width="100%"
425 cellspacing=0 cellpadding=5 border=0><tr><td
426 ><font color="#808080"><small>
427 Roundup could be distributed with a few
428 suggested schemas for different purposes.
429 One possible enhancement to the
430 software-development schema is
431 a <em>reference</em> property
432 named <strong>implements</strong> for connecting
433 development items to design requirements which
434 they satisfy, which should
435 be enough to provide basic support for
436 <a href="http://software-carpentry.codesourcery.com/lists/sc-discuss/msg00046.html">traceability</a>.
437 Clearly there is also potential for adding
438 properties for related source files, check-ins,
439 test results, regression tests for resolved items,
440 and so on, though these have not yet been
441 sufficiently well thought out to specify here.
442 </small></font></td></tr></table></td></tr></table>
443 <p>It is hoped that the hyperdatabase together with the
444 specializations mentioned above for Roundup will be
445 applicable in a variety of situations
446 (in accordance with our guiding principle of <em>generality</em>).
447
448 <p>To address the problem at hand, we need
449 a specific schema for items applied particularly to software development.
450 Again, we are trying to keep the schema simple: too many
451 options make it tougher for someone to make a good choice.
452 The schema is written here in the same form that it would
453 appear in a configuration file.
454 <br clear=all>
455
456 <pre>
457     fixer = Reference()             # people who will fix the problem
458
459     topic = Reference()             # relevant topic keywords
460
461     priority = Choice("critical",   # panic: work is stopped!
462                       "urgent",     # important, but not deadly
463                       "bug",        # lost work or incorrect results
464                       "feature",    # want missing functionality
465                       "wish")       # avoidable bugs, missing conveniences
466
467     status = Choice("unread",       # submitted but no action yet
468                     "deferred",     # intentionally set aside
469                     "chatting",     # under review or seeking clarification
470                     "need-eg",      # need a reproducible example of a bug
471                     "in-progress",  # understood; development in progress
472                     "testing",      # we think it's done; others, please test
473                     "done-cbb",     # okay for now, but could be better
474                     "resolved")     # fix has been released
475 </pre>
476
477 <p>The <strong>fixer</strong> property assigns
478 responsibility for an item to a person or a list of people.
479 The <strong>topic</strong> property places the
480 item in an arbitrary number of relevant topic sets (see
481 <a href="#browse">the section on Browsing and Searching</a>).
482
483 <p>As previously mentioned, each item gets an activity log.
484 Whenever a property on an item is changed, the log
485 records the time of the change, the user making the change,
486 and the old and new values of the property.  This permits
487 the later gathering of statistics (for example, the average time
488 from submission to resolution).
489
490 <p>We do not specify or enforce a state transition graph,
491 since making the system rigid in that fashion is probably more
492 trouble than it's worth.
493 Experience has shown that there are probably
494 two convenient automatic state transitions:
495
496 <ul>
497 <li>from <strong>unread</strong> to <strong>chatting</strong>
498 when e-mail is written about an item
499 <li>from <strong>testing</strong> to <strong>resolved</strong>
500 when a new release of the software is made
501 </ul>
502
503 Beyond these, in accordance with our principle of <em>generality</em>,
504 we allow access to the hyperdatabase
505 API so that scripts can automate transitions themselves or
506 be triggered by changes in the database.
507
508 <p><hr>
509 <h2><a name="ui">User Interface</a></h2>
510
511 <p>Roundup provides its services through two main interfaces:
512 e-mail and the Web.
513 This division is chosen to optimize the most common tasks.
514
515 <p>E-mail is best suited for
516 the submission of new items since most people are most comfortable
517 with composing long messages in their own favourite e-mail client.
518 E-mail also permits them to mention URLs or attach files relevant
519 to their submission.  Indeed, in many cases people are already
520 used to making requests by sending e-mail to a mailing list
521 of people; they can do exactly the same thing to use Roundup
522 without even thinking about it.
523 Similarly, people are already
524 familiar with holding discussions in e-mail, and plenty of
525 valuable usage conventions and software tools already exist for that medium.
526
527 <p>The Web, on the other hand, is best suited for summarizing
528 and seeking information, because it can present an interactive
529 overview of items.  Since the Web has forms, it's also
530 the best place to edit items.
531
532 <h3><a name="discuss">Submission and Discussion</a></h3>
533
534 <p><table align=right width="40%" bgcolor="#808080" cellpadding=0 border=0
535 ><tr><td><table bgcolor="#e8e8e8" width="100%" cellspacing=0 cellpadding=5
536 border=0><tr><td><font color="#808080"><small>
537 Nosy lists have actually been tried in practice,
538 and their emergent properties have
539 turned out to be very effective.
540 They are one of the key strengths of the Roundup prototype,
541 and often cause me to wonder if all mailing lists ought to work this way.
542 Roundup could even replace Hypermail.
543 </small></font></td></tr></table></td></tr></table>
544
545 <p>The system needs an address for receiving mail
546 and an address that forwards mail to all participants.
547 Each item has its own list
548 of interested parties, known as its <em>nosy list</em>.
549 Here's how nosy lists work:
550
551 <p><ol type="a">
552 <li>New items are always submitted by sending an e-mail message
553 to Roundup.  The "Subject:" field becomes the description
554 of the new item.
555 The message is saved in the mail spool of the new item,
556 and copied to the list of all participants
557 so everyone knows that a new item has been added.
558 The new item's nosy list initially contains the submitter.
559
560 <li>All e-mail messages sent by Roundup have their "Reply-To:"
561 field set to Roundup's address, and have the item's
562 number in the "Subject:" field.  Thus, any replies to the
563 initial announcement and subsequent threads are all received
564 by Roundup.  Roundup notes the item number in the "Subject:"
565 field of each incoming message and appends the message
566 to the appropriate spool.
567
568 <li>Any incoming e-mail tagged with an item number is copied
569 to all the people on the item's nosy list,
570 and any users found in the "From:", "To:", or "Cc:" fields
571 are automatically added to the nosy list.  Whenever a user
572 edits an item's properties in the Web interface, they are
573 also added to the nosy list.
574 </ol>
575
576 <p>The effect
577 is like each item having its own little mailing list,
578 except that no one ever has to worry about subscribing to
579 anything.  Indicating interest in an issue is sufficient, and if you
580 want to bring someone new into the conversation, all you need to do
581 is Cc: a message to them.  It turns out that no one ever has to worry
582 about unsubscribing, either: the nosy lists are so specific in scope
583 that the conversation tends to die down by itself when the issue is
584 resolved or people no longer find it sufficiently important.
585
586 <p>Each nosy list is like an asynchronous chat room,
587 lasting only a short time (typically five or ten messages)
588 and involving a small group of people.
589 However, that
590 group is the <em>right</em> group of people:
591 only those who express interest in an item in some way
592 ever end up on
593 the list, so no one gets spammed with mail they
594 don't care about, and no one who <em>wants</em>
595 to see mail about a particular item needs to be left
596 out, for they can easily join in, and just as easily
597 look at the mail spool on an item to catch up on any
598 messages they might have missed.
599
600 <p>We can take this a step further and
601 permit users to monitor particular topics or
602 classifications of items
603 by allowing other kinds of nodes to
604 also have their own nosy lists.
605 For example, a manager could be on the
606 nosy list of the priority value node for "critical", or a
607 developer could be on the nosy list of the
608 topic value node for "security".
609 The recipients are then
610 determined by the union of the nosy lists on the
611 item and all the nodes it links to.
612
613 <p>Using many small, specific mailing lists results
614 in much more effective communication than one big list.
615 Taking away the effort of subscribing and unsubscribing
616 gives these lists the "feel" of being cheap and
617 disposable.
618
619 The transparent capture of the mail spool attached to each
620 issue also yields a nice knowledge repository over time.
621
622
623 <h3><a name="edit">Editing</a></h3>
624
625 <p>
626 <img src="images/edit.png" align=right width=171 height=471 alt="">
627 Since Roundup is intended to support arbitrary user-defined
628 schema for item properties, the editing interface must be
629 automatically generated from the schema.  The configuration for
630 Roundup will include a template describing how to lay out the
631 properties to present a UI for inspecting and editing items.
632 For example:
633
634 <pre>
635     &lt;table width="100%"&gt;
636     &lt;tr&gt;&lt;td align=right&gt;Description:&lt;/td&gt;
637         &lt;td&gt;&lt;?property description size=70&gt;&lt;/td&gt;&lt;/tr&gt;
638     &lt;tr&gt;&lt;td align=right&gt;Status:&lt;/td&gt;
639         &lt;td&gt;&lt;?property status&gt;&lt;/td&gt;&lt;/tr&gt;
640     &lt;/table&gt;
641 </pre>
642
643 <p>To display the editing form for an item, Roundup substitutes
644 an HTML form widget for each <tt>&lt;?property </tt>...<tt>&gt;</tt>
645 tag, and transfers attributes
646 (such as <tt>size=70</tt> in the above example)
647 from the processing tag to the form widget's tag.
648 Each type has its own appropriate editing widget:
649 <ul>
650 <li><em>string</em> properties appear as text fields
651 <li><em>date</em> properties appear as text fields
652 <li><em>choice</em> properties appear as selection lists
653 <li><em>reference</em> properties appear as multiple-selection lists
654 with a text field for adding a new option
655 </ul>
656
657 <p>We foresee the use of custom date fields for things like deadlines,
658 so input fields for <em>date</em> properties should support some
659 simple way of specifying relative dates (such as "three weeks from now").
660
661 <p>The <strong>superseder</strong> property is a special case:
662 although it is more efficient to store a <strong>superseder</strong>
663 property in the superseded item, it makes more sense to provide
664 a "supersedes" edit field on the superseding item.  So we need
665 a special widget on items for this purpose (perhaps something
666 as simple as a text field containing a comma-separated list of
667 item numbers will do).  Links in the <strong>superseder</strong> property
668 should appear on both the superseding and superseded items to
669 facilitate navigating an item's pedigree.
670
671 <p>After the editing widgets, the item inspection page shows
672 a "note" text box and then a display of the messages in the
673 discussion spool, like the Roundup prototype.  This field
674 lets you enter a note explaining your change when you edit the
675 item, and the note is included in the notification message that
676 goes out to tell the interested parties on the nosy list of
677 your edits.
678
679 <h3><a name="browse">Browsing and Searching</a></h3>
680
681 <p>The ideal we would like to achieve is to make searching as
682 much like browsing as possible: the user simply clicks about
683 on things that seem interesting, and the information narrows
684 down comfortably until the goal is in sight.  This is preferable
685 to trying to digest a screen filled with widgets and buttons
686 or entering a search expression in some arcane algebraic syntax.
687
688 <p><table align=right width="40%" bgcolor="#808080" cellpadding=0 border=0
689 ><tr><td><table bgcolor="#e8e8e8" width="100%" cellspacing=0 cellpadding=5
690 border=0><tr><td><font color="#808080"><small>
691 Though the generation of each page amounts to a database query,
692 so that the underlying mechanism is still a series of queries and
693 responses, the user interface never separates the query from
694 the response, so the <em>experience</em> is one of stepwise
695 refinement.
696 </small></font></td></tr></table></td></tr></table>
697 While a one-shot search may be appropriate when you're
698 looking for a single item and you know exactly what you want, it's
699 not very helpful when you want an overview of
700 things ("Gee, there are a lot more high-priority items than
701 there were last week!") or trying to do comparisons ("I have
702 some time today, so who is busiest and could most use some help?")
703 <br clear=all>
704
705 <p>The browsing interface presents filtering
706 functionality for each of the properties in the schema.  As with
707 editing, the interface is generated from a template
708 describing how to lay out the properties.
709 Each type of property has its own appropriate filtering widget:
710 <ul>
711 <li><em>string</em> properties appear as text fields supporting
712 case-insensitive substring match
713 <li><em>date</em> properties appear as a text field with an
714 option to choose dates after or before the specified date
715 <li><em>choice</em> properties appear as a group of
716 selectable options
717 (the filter selects the <em>union</em> of the sets of items
718 associated with the active options)
719 <li><em>reference</em> properties appear as a group of
720 selectable options
721 (the filter selects the <em>intersection</em> of the sets of items
722 associated with the active options)
723 </ul>
724
725 <p>For a <em>reference</em> property like <strong>topic</strong>,
726 one possibility is to show, as hyperlinks, the keywords whose
727 sets have non-empty intersections with the currently displayed set of
728 items.  Sorting the keywords by popularity seems
729 reasonable.  Clicking on a keyword then narrows both the list of items
730 and the list of keywords.  This gives some of the feel of walking
731 around a directory tree -- but without the restriction of having
732 to select keywords in a particular hierarchical order, and without
733 the need to travel all the way to the leaves of the tree before
734 any items are visible.
735
736 <p>Below the filtering form is a listing of items, with their
737 properties displayed in a table.  Rows in the table can also be
738 generated from a template, as with the editing interface.
739 This listing is the central overview of the system, and it
740 should aim to maximize the density of
741 useful information in accordance with our guiding principle of
742 <em>efficiency</em>.
743 For example, 
744 <a href="http://www.lfw.org/ping/bugzilla-4.gif">Bugzilla
745 initially displays seven or eight items of the index</a>, but only
746 after the user has 
747 <a href="http://www.lfw.org/ping/bugzilla-1.gif">waded</a>
748 through
749 <a href="http://www.lfw.org/ping/bugzilla-2.gif">three</a>
750 bewildering
751 <a href="http://www.lfw.org/ping/bugzilla-3.gif">screens</a> of
752 form widgets.
753 <a href="http://www.lfw.org/ping/jitterbug-1.gif">Jitterbug can't
754 even fit any items at all in the first screenful</a>, as it's
755 taken up by artwork and adminstrative debris.  In contrast,
756 <a href="http://www.lfw.org/ping/roundup-1.gif">in the
757 Roundup prototype,
758 25 high-priority issues are immediately visible</a>, with
759 most of the screen space devoted to their descriptions.  
760 Colour indicates
761 the status of each item to help the eye sift through the index quickly.
762
763 <p>In both Jitterbug and Bugzilla, items are sorted by default by ID,
764 a meaningless field.  Sorting by ID puts the issues in order by
765 ascending submission date, which banishes recent issues far away
766 at the bottom of the list.
767 The Roundup prototype sorts items
768 in sections by priority, and then within sections by the date
769 of last activity.  This reveals at a glance where discussion is
770 most active, and provides an easy way for anyone to move an issue
771 up in the list.
772
773 <p>The page produced by a given set of browsing options constitutes
774 a <em>view</em>.  The options should all be part of the query
775 parameters in the URL so that views may be bookmarked.  A view
776 specifies:
777
778 <ul>
779 <li>search strings for string properties
780 <li>date ranges for date properties
781 <li>acceptable values for choice properties
782 <li>required values for reference properties
783 <li>one or more sort keys
784 <li>a list of properties for which to display filtering widgets
785 </ul>
786
787 <p>On each sort key there is the option to use sections -- that is,
788 instead of making the property's value a column of the table, each
789 possible value for the property
790 is displayed at the top of a section and all the items having
791 that value for that property are grouped underneath.  This avoids
792 wasting screen space with redundant information.
793
794 <p>We propose that our default view should be:
795
796 <ul>
797 <li>all options on for <strong>priority</strong> and <strong>fixer</strong>
798 <li>all options on except "resolved" for <strong>status</strong>
799 <li>no options on for <strong>topic</strong>
800 <li>primary sort by <strong>priority</strong> in sections
801 <li>secondary sort by decreasing <strong>activity</strong> date
802 </ul>
803
804 <p>The starting URL for Roundup should immediately present the listing of
805 items generated by this default view, with no
806 preceding query screen.
807
808 <p><hr>
809 <h2><a name="devplan">Development Plan</a></h2>
810
811 <p>The hyperdatabase is clearly a separable component which
812 can be developed and tested independently to an API specification.
813
814 <p>As soon as the API to the hyperdatabase is nailed down,
815 the implementation of the Roundup database layer
816 on top of the hyperdatabase can begin.
817 (This refers to the data types and five fixed properties
818 specific to Roundup.)  This layer can also be tested separately.
819
820 <p>When the interface to the Roundup hyperdatabase is ready,
821 development can begin on the user interface.  The mail handler
822 and the Web interface can be developed in parallel and mostly
823 independently of each other.
824
825 <p>The mail handler can be set up for testing fairly easily:
826 mail messages on its standard input can be synthesized;
827 its output is outgoing mail, which can be
828 captured by replacing the implementation of the
829 "send mail" function; and its side effects appear in the
830 hyperdatabase, which has a Python API.
831
832 <p>The Web interface is not easily testable in its entirety,
833 though the most important components of it can be unit tested,
834 such as the component that translates a view specification
835 into a list of items for display, and
836 the component that performs replacements on templates
837 to produce an editing or filtering interface.
838
839 <p><hr>
840 <h2><a name="issues">Open Issues</a></h2>
841
842 <p>The description of the hyperdatabase above avoids some
843 issues regarding node typing that need to be better specified.
844 It is conceivable that eventually Roundup
845 could support multiple kinds of items with their own schemas.
846
847 <p>To permit integration with external tools, it is probably
848 a good idea to provide a command-line tool that exposes the
849 hyperdatabase API.  This tool will be left for a later phase
850 of development and so isn't specified in detail here.
851
852 <p>Generating the user interface from a template is like
853 applying an XSL stylesheet to XML, and if there's a standard
854 Python module for performing these transformations, we could
855 use XML instead.
856
857 <p>More thinking is needed to determine the best filtering
858 interface for <em>reference</em> properties.
859 The proposed interface works well for topic keywords, but
860 it isn't clear what to do when there are too many keywords
861 to display them all.
862
863 <p>There has been a variety of reactions to the hyperdatabase
864 from reviewers: some like it, some are neutral, and some
865 would prefer a "standard" RDBMS solution.
866 For those in the latter camp, note
867 that it's still possible to build the Roundup database layer
868 around an RDBMS if we really need to.  The rest of the design, in
869 particular the "nosy list" mechanism, remains intact.
870
871 <p>The possibility of malice by registered users has been disregarded.
872 The system is intended to be used by a co-operative group.
873
874 <p>This design tries to address as many as possible of the
875 suggested requirements mentioned on
876 <a href="http://software-carpentry.codesourcery.com/sc_track">the contest page</a>:
877
878 <ul>
879 <li>configuring states: Edit the schema.
880 <li>setting state transition rules: We don't enforce any rules.
881 <li>assigning responsibility: Set the <strong>fixer</strong> property.
882 <li>splitting and joining: Use the <strong>superseder</strong> property.
883 <li>hiding information: Add
884 a property and a pre-defined view that filters on it.
885 <li>secure protocols: Naturally HTTPS would be nice, though it's largely
886 a webserver configuration issue; secure e-mail is not addressed.
887 <li>archiving old issues: Tag them with a property.
888 <li>identifying repeated issues: Use the <strong>superseder</strong> property.
889 <li>connecting state changes to external operations: We provide an
890 API to the database and the notification mechanism so it can be scripted.
891 <li>non-Latin alphabets: Unicode in Python 1.6 will handle
892 this for string properties, and we can leverage existing standards for
893 internationalizing e-mail messages.
894 <li>images and other binaries: Attach them to e-mail messages.
895 <li>inspecting item state: Use the editing interface.
896 <li>translation between system-dependent formats: This is not addressed.
897 <li>performing searches: Use the browsing and filtering interface.
898 <li>collecting statistics: Information is gathered in the activity log,
899 though tools to summarize it are not described here.
900 </ul>
901
902 <p><hr>
903 <h2><a name="summary">Summary</a></h2>
904
905 <p>Roundup is an issue-tracking system that also functions as
906 a communications center and a knowledge repository.  It combines
907 the strengths of e-mail and the Web to try to provide the best
908 possible user interaction.
909
910 <ul>
911 <li>The submission and discussion of items by e-mail, permitting
912 participants to use an easy and familiar tool, achieves our goal
913 of <em>low barrier to participation</em>.
914 <li>The generic link-based structuring of data and use of
915 incremental filtering rather than one-shot querying makes for
916 <em>straightforward navigation</em>.
917 <li>The use of <em>nosy lists</em> (a powerful replacement for
918 e-mail discussion lists) to manage communication on
919 a fine-grained level provides <em>controlled information flow</em>.
920 </ul>
921
922 <p>The use of a "hyperdatabase" as the core model for
923 the knowledge repository gives us the flexibility to extend
924 Roundup and apply it to a variety of domains by
925 providing new item schemas and user-interface templates.
926
927 <p>Roundup is self-contained and easy to set up, requiring
928 only a webserver and a mailbox.  No one needs to be root to
929 configure the webserver or to install database software.
930
931 <p>This design is based on an existing deployed
932 prototype which has proven its strengths and revealed its
933 weaknesses in heavy day-to-day use by a real development team.
934
935 <p><hr>
936 <h2><a name="ack">Acknowledgements</a></h2>
937
938 <p>My thanks are due to 
939 Christina Heyl, Jesse Vincent, Mark Miller, Christopher Simons,
940 Jeff Dunmall, Wayne Gramlich, and Dean Tribble
941 for reviewing this paper and contributing their suggestions.
942
943 <p><hr><p>
944
945 <center>
946 <table>
947 <tr>
948 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/index.html"><b>[Home]</b></a>&nbsp;&nbsp;&nbsp;</td>
949 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/faq.html"><b>[FAQ]</b></a>&nbsp;&nbsp;&nbsp;</td>
950 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/license.html"><b>[License]</b></a>&nbsp;&nbsp;&nbsp;</td>
951 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/contest-rules.html"><b>[Rules]</b></a>&nbsp;&nbsp;&nbsp;</td>
952 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/biblio.html"><b>[Resources]</b></a>&nbsp;&nbsp;&nbsp;</td>
953 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/lists/"><b>[Archives]</b></a>&nbsp;&nbsp;&nbsp;</td>
954 </tr>
955 </table>
956 </center>
957
958 <p><hr>
959 <center>
960 Last modified 2001/04/06 11:50:59.9063 US/Mountain
961 </center>
962 </body></html>