Process and Editorial suggestions

["Orchard, David" <dorchard@jamcracker.com>]

I have a number of suggestions for the process of discussing issues and
editorial format for issues in the various documents.  I've proposed these
ideas to the use case and bindings teams with some general agreement.  It
seems appropriate to bring to the larger group then.  The follow ups can be
between editors if they think it appropriate.

  Issues format

Issues should follow the following template in the documents:

ISSUE:[Document/Section Abbreviation-Issue Number: Short name]
Issue long description.  
Possible resolutions, with optional editor resolution
Decision

<sample type="text">
ISSUE[UC-01:Framework] Should A2ML provide a framework that allows delivery
of security content negotiated out-of-band.  A typical use case is
authorization extensions to the core A2ML constructs.  The contra-position
is to rigidly define the constructs without allowing extension.

Possible Resolutions:
1. Specify only the explicitly allowable content of messages, no framework
2. Allow full extensibility of message content (verbs and nouns) as well as
flexible intermediary processing
3. Allow full extensibility of message content (verbs and nouns) with
rigidly defined intermediary processing.

</sample type="text">

I include an example from an old draft of XInclude.  There is some irony in
including an xinclude example).  
<sample type="text/xml" >
<issue id="&propname;:24-range-inclusions">
	<p>When the href attribute specifies a range, should the range nodes
be included in order or should ranges be disallowed.  Currently decided to
disallow.</p></issue>
</sample>

Also to editors: note the use of an XML entity to enable easy name changes.
XInclude has been formerly known as XML Include, SNIP (Simple Node Inclusion
Proposal), and YAXI (Yet Another XML Inclusion proposal)

The use of an abbreviation, a number, and a short text string allows for
easy discussion in email.  One of the problems with XP's lack of the text
string in requirements or issue identifiers is that users have to open an
email if the haven't internalized the hashtable of name value pairs.  The
use of the abbreviation helps the issues list viewers to know which section
or document is being referred to.  Numbering helps us determine progress (50
issues created, 20 still open).

  Issue Process

The issues should be embedded in the document where the issue occurs.  There
is an issues document which can be created by extracting the issue content
from the documents.  We should eventually structure our meetings around
resolving outstanding issues in some deterministic manner.  On W3C Working
Groups, we've generally picked a few issues a week to resolve.   The issues
document shows the open and resolved issues.  When an issue is closed, it is
removed from the originating document.  Perhaps copied by value into the
issues document or having a new attribute indicated "resolved" added to the
issue schema.

When the issues have been selected for discussion, the chair of the
subcommittee or the issues list owner should post 1 email per issue to the
mailing list.  1 issue per email is important for threading of the
discussion.  The subject of the email is simply the issue identifier, ie
Subject: UC-01:Framework

  Requirements Process

I suggest the same process would work for requirements.  We are on the path
right now of classifying each requirement as an issue, whereas we could just
identify and debate each requirement as requirements.  I'm sure some
engineous xml person could come up with a base type that would enable both
requirement and issue tracking.

My $0.04 worth.

Cheers,
Dave Orchard
XML Architect
Jamcracker Inc.,    19000 Homestead Dr., Cupertino, CA 95014
p: 408.864.5118     m: 604.908.8425    f: 408.725.4310

Named to Red Herring's list of 100 Most Important Companies:
www.redherring.com/mag/issue79/herring100/jamcracker.html