OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

chairs message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Re: [chairs] Draft: proposed process for comment handing


That looks good. I want to stay away from having comments in a spread sheet though. That makes them opaque to the search engines. I suppose we could say "you can also put them in" but I do want to see the text of the comment in the email. I think that's important. 

I have looked at the system that the BSI uses and I plan to look at other systems that would give us form entry this coming year. An approach like that would be a big improvement. For now though we have to use the -comment@ lists. 

/chet


On Fri, Dec 21, 2012 at 1:35 PM, Ken Laskey <klaskey@mitre.org> wrote:
Chet,

This looks good for a first pass but let me tweak it a bit.

The TC requests that reviewers provide feedback to include the following information

Initial page number:   
First line number:
Lines/Range:        
Issue/Comment:
Proposed Change:

At the TC's request, If possible, please add your comment to the attached spreadsheet [whatever characterizes the provided medium] and return this as an attachment to the -comment list.  If using the spreadsheet is not convenient, please clearly provide the requested information in your email.

Goal #1 is to clearly get consistent comments that require as little interpretation of format as possible.  Goal #2 is to get it in a format that makes it easiest for the TC to process, under the assumption that this will improve the quality of the processing.  We'll sacrifice Goal #2 if necessary; we'd prefer to achieve Goal #1 if at all possible.

Note, the spreadsheet verbiage may be completely off if something like Web entry of comments is used, but the intent is to clearly provide the preferred capture mechanism.

Ken


On Dec 21, 2012, at 12:12 PM, Chet Ensign wrote:

Ken, below I have mocked up how I could envision incorporating a TC's request regarding comments format into a public review announcement. I've created a fictional SOA-RAF 15 day public review. I'd include it at the request of the TC. Does this give you what you are looking for? 

--- prototype 15 day review announcement

The SOA Reference Model TC [1] members have recently approved a Committee Specification Draft (CSD) and submitted this specification for 15-day public review:

Reference Architecture Foundation for Service Oriented Architecture Version 1.0 
Committee Specification Draft 03 / Public Review Draft 03
04 December 2012 

Specification Overview:

<TC's description / abstract goes here> 

Public Review Period:

The public review starts <date> and ends <date + 15>.

This is an open invitation to comment. OASIS solicits feedback from potential users, developers and others, whether OASIS members or not, for the sake of improving the interoperability and quality of its technical work.

The TC requests that reviewers provide feedback in the following form: 

Initial page number:   
First line number:
Lines/Range:        
Issue/Comment:
Proposed Change:

URIs: 
<and the standard announcement text goes on from here> 

---

/chet


On Thu, Dec 20, 2012 at 5:42 PM, Ken Laskey <klaskey@mitre.org> wrote:
Chet,

"only" is obviously an inoperable phrase.  

I have never seen a review announcement that attaches a preferred comments disposition log.  If we can, that satisfies my request.

Basically, what I would like to be able to do is say to reviewers is this is the information that you should easily be able to provide and that the TC feels will make your comments and concerns clear.  (The specifics may vary fromTC to TC.)  Providing this information will allow us to respond to those concerns.  If you can provide it in a certain format -- say, fill in the attached Excel spreadsheet and attach it to an email to -comment -- that would be very helpful but our major intent is to clearly get your comment.

I will better be able to translate blithering gibberish or well-meaning comments in another format if the majority of input is easy to process.

One small item is I would like my request format to just concentrate on the inputs I need from the submitter.  The submitter doesn't need a column for email URL when that is something I fill in later.  However, the final consolidated capture will contain all elements required by process.

Ken


On Dec 20, 2012, at 10:04 AM, Chet Ensign wrote:

Hi Ken - regarding "My request is that a TC be able to indicate the preferred format and content for issue submission," are you suggesting that you would like the TC to be able to tell commenters that 'we'll only take comments like this or that?" The TC Process won't allow for that. Comments have to be provided by email to the -comment@ mailing list and the TC has to acknowledge them. The TC can certainly request comment providers use a form that works for them but they cannot require it. 

Does that mean someone could send an email of blithering gibberish and the TC would have to acknowledge, track and dispose of it? Yes, I'm afraid it does. However, that's the rule as it stands so I'm not able to ignore it or change it. That's a job for the Board Process Committee. 

Where I can provide flexibility is in what you all can provide to me. I am happy to accept whatever form the TC wants to use to provide the comment disposition log so long as (a) it is a stand-alone document in a commonly used format (e.g. odt, doc, xls, txt, rtf) and (b) it includes the facts that I listed. I see no problem at all with your spread sheet so long as I have the email links in it as well for tracking back. 

Maybe I've misunderstood your suggestion? 

/chet


On Thu, Dec 20, 2012 at 8:51 AM, Ken Laskey <klaskey@mitre.org> wrote:
Chet,

If you compare the spreadsheet you provided as an example and the spreadsheet column headings I noted, you see a difference in what is captured corresponding to the different purposes they serve.  The headings were what the SOA-RM TC found useful when getting comment information; the sample spreadsheet focuses more on information needed for the roll-up. Both serve the final goal of accepting, compiling, and processing issues.  

My request is that a TC be able to indicate the preferred format and content for issue submission so they can efficiently combine issues and add the information needed for the roll-up.  Even if someone does not have access to Excel, if they can provide information as text but that obviously maps to what goes into the spreadsheet, that will save time and improve accuracy of the capture.

Ken
---------------------------------------------------------------------------
Dr. Kenneth Laskey
MITRE Corporation, M/S H305             phone: 703-983-7934
7515 Colshire Drive                             fax: 703-983-1379
McLean VA 22102-7508

On Dec 20, 2012, at 8:33 AM, Chet Ensign wrote:

Hi Ken, 

Yes, that is exactly my intention. I want to provide simple, generic templates for any TCs who want me to give them something to start with. If the SOA-RM TC finds a richer set of data works better for them, I'll be be happy to take that as well. 

I will be happy with whatever format the TC wishes to provide so long as that basic set of facts from the proposal is in it -- and that it is in a format that the rest of the world can open  and read without the need for special software. 

/chet


On Wed, Dec 19, 2012 at 8:18 PM, Ken Laskey <klaskey@mitre.org> wrote:
Chet,

Is it possible for the TC to supply a proposed template for comments?  For example, the SOA-RM TC found that a spreadsheet with the column headings

Initial page    First line       Lines/Range        Submitter                  Issue/Comment                     Proposed Change

worked well for us.  Combining issues from multiple submitter into one document was a simple cut and paste.  Then, it let us unambiguously identify the text in question, easily sort issues (using First line) from multiple submitters by where it was in the text, and see clearly what submitters suggested be done to a given portion of text.  

Now, this isn't to say that other formats wouldn't be equally as effective, but a TC providing its preferred format can spend less time on collection, be more accurate in the collection, and can more quickly focus on resolution.

Many of the other elements that need to be captured, such as the link to the incoming email, can easily be added -- in our case as other columns in the consolidated spreadsheet -- while letting the submitter concentrate on comments.

Ken

---------------------------------------------------------------------------
Dr. Kenneth Laskey
MITRE Corporation, M/S H305             phone: 703-983-7934
7515 Colshire Drive                             fax: 703-983-1379
McLean VA 22102-7508

On Dec 19, 2012, at 7:02 PM, Chet Ensign wrote:

Chairs,

I will circulate this to the broader membership after a review with you.

Last April, I opened a conversation about how to enable the OASIS requirements for handling comments to be met while minimizing the procedural impact on TCs. (The thread started here: https://lists.oasis-open.org/archives/chairs/201204/msg00020.html) The observations and insights offered were valuable. This email lays out the next step towards implementing a consistent process.

Below is my proposal for a procedure that I think meets the consensus from that conversation to (a) keep it simple, (b) provide options while (c ) meeting the TC Process requirements. I have attached a couple of sample templates based on the samples offered that could be used to record comments and their dispositions. Use of these won't be required, they will just be provided for the convenience of the TCs that want something to use as a starting point.

Please have a look at this over the next few weeks and share your thoughts with me. I will ask for broader feedback in January with a goal of documenting this, announcing it and then putting it into practice on or about February 1st. Note that the procedure will not be retroactive - it will apply to work started from its effective date forward.

To be clear, this changes nothing about the current requirements documented in the TC Process. This simply provides a consistent means for TCs and TC Admin to work together to meet the requirements - something that has been lacking to date.


1. TC Obligations With Respect to Comments

The requirements for handling comments are laid out in sections 2.2, 2.8, 3.2 and 3.4 of the OASIS TC Process. Those requirements are: 

- That comments be received only through the TC's <short name>-comment@lists.oasis-open.org mailing list.

- That comments be received by one or more members of the TC including the chair.

- That comments be acknowledged.

- That comments be tracked and their resolutions documented:

a) During a proposed TC call for comment period;
b) During a public review of a TC work product;
c) During a public review of a Candidate OASIS Standard.

- And that at the end of the comment / review period, the TC post to its email list an account of each of the issues raised during the public review  along with its resolution.


2. Proposed Procedure for Meeting These Obligations

Here are the proposed steps for a TC to take to meet the requirements. 

a) The TC Chair, at a minimum, must subscribe to the TC's <tcname>-comment@lists.oasis-open.org mailing list. It will likely make sense for another TC member (e.g. secretary, editor) to be assigned to subscribe to the list and track and report comments and issues back to the TC.

b) Someone from the TC must acknowledge that the TC has received the comment by sending an email acknowledgement to the provider. A simple "thank you for your comment; the TC will be consider it" message is sufficient.

c) The TC must track each comment received and how the group decides to resolve it. Per the TC Process, a TC is not required to take any action on the substance of the comment, but the decision not to must be recorded.

The TC can choose to track comments and resolutions however they wish: in a word processing document, in a spread sheet, in JIRA, in the TC wiki. The TC must at a minimum record:

+ The date the comment was received;
+ A link to the email in which a comment was received;
+ The name of the person or entity providing the comment;
+ A brief summary of the comment;
+ A statement of the TC’s decision on how to handle the comment, in as much detail as the TC wishes to provide.

In the event that a single email provides multiple comments or issues, each must be listed, tracked and resolved separately.

The list need not be cumulative however keeping a cumulative list is likely to be more convenient when the time comes that you want to submit a Committee Specification as a Candidate OASIS Standard. The TC Process states that, before an OASIS membership ballot can be held on a COS, the TC must provide "a pointer to an account of each of the comments/issues raised during the public review period(s), along with its resolution." Having all the comments and their resolutions stored in one list will make satisfying this requirement easy.

d) Four weeks after the end of a public review will be deemed "the end of the review period." By this point at the latest, the TC must post to its email list a document containing, at a minimum, the pieces of information listed above. The document can be either a word processing document or a spread sheet but it must be a document that can be opened and read by any interested party. 

If the TC is using JIRA or some other means to track comments, a document must be created by exporting the information from that source.

If the document is a cumulative list of comments and resolutions, it should also contain, for each comment, identification of the draft to which it applied.

The posting email can be created by loading the document into the TC's document repository and using the automatically generated email to produce the pointer or by attaching the document directly to the email.

With that email, the TC obligations will be considered fully met.


3. What TC Administration Will Do With the Comment Resolution Document

A key objective here is to ensure that comments and their resolutions can readily be found by other who are interested in the TCs work. Here is what TC Admin will do with the documents.

a) When the TC is ready to take another action on its work product (e.g. request another public review, request a ballot to approve a Committee Specification), a pointer back to this document will have to be provided as part of the support request. TC Administration will not proceed with a requested action until the comment resolution document is provided.

b) A link to the comment resolution document will be included in the announcements of subsequent public reviews, document approvals, Special Majority ballots and other communications where it will provide additional, useful information. 

c) The comment resolution documents will also be stored in the OASIS Library along with the public review drafts to which they apply. This will help to ensure transparency and traceability between comments received during a public review and their resolution.

Thanks very much for your feedback and help putting a process in place. My best wishes to you all for happy holidays.

Best regards,

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

 
 




<draft-comment-resolution-list.xls><draft-comment-resolution-list.odt><draft-comment-resolution-list.ods><draft-comment-resolution-list.doc>




--

/chet 
----------------
Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393 

Check your work using the Support Request Submission Checklist at http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html 

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn:    http://linkd.in/OASISopen
Twitter:        http://twitter.com/OASISopen
Facebook:  http://facebook.com/oasis.open




--

/chet 
----------------
Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393 

Check your work using the Support Request Submission Checklist at http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html 

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn:    http://linkd.in/OASISopen
Twitter:        http://twitter.com/OASISopen
Facebook:  http://facebook.com/oasis.open




--

/chet 
----------------
Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393 

Check your work using the Support Request Submission Checklist at http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html 

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn:    http://linkd.in/OASISopen
Twitter:        http://twitter.com/OASISopen
Facebook:  http://facebook.com/oasis.open




--

/chet 
----------------
Chet Ensign
Director of Standards Development and TC Administration 
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393 

Check your work using the Support Request Submission Checklist at http://www.oasis-open.org/committees/download.php/47248/tc-admin-submission-checklist.html 

TC Administration information and support is available at http://www.oasis-open.org/resources/tcadmin

Follow OASIS on:
LinkedIn:    http://linkd.in/OASISopen
Twitter:        http://twitter.com/OASISopen
Facebook:  http://facebook.com/oasis.open


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]