RE: [ws-rx-editors] Improvements to our editorial workflow

["Marc Goodner" <mgoodner@microsoft.com>]

Umit, 

All of the input did not come after the docs were published. Please see
my feedback below on this same thread. Every editorial comment I made
against the wd-05 version, before it was even approved as a CD,
persisted into the CD. The other issues were introduced into the CD
after the wd-05 version. I already apologized for not reviewing the CD
before it was published. Now that it has been and I have reviewed it I
think logging an issue with the errors I found is appropriate.

Yes there is something we can do than just publish documents without
review. We should ask for people to review the docs before they are
published and give them a deadline to do so by. If the deadline is not
met the spec in question should not be published and we should report to
the TC that it is still in progress. The chairs can then apply
appropriate pressure or ask for other volunteers to assist from the TC
membership.

I have no argument against pairing up to review documents. I think that
is a fine suggestion.

As this thread progresses I suggest we should capture the suggestions to
improve our process into a document that includes a checklist similar to
what Peter sent to the ws-rx list last week [1].

Regards, Marc g

1 Namespaces/Identifiers/other editorial things
http://lists.oasis-open.org/archives/ws-rx/200511/msg00096.html


-----Original Message-----
From: Yalcinalp, Umit [mailto:umit.yalcinalp@sap.com] 
Sent: Tuesday, November 08, 2005 3:16 PM
To: Marc Goodner; Gilbert Pilz; ws-rx-editors@lists.oasis-open.org
Subject: RE: [ws-rx-editors] Improvements to our editorial workflow

If the editors did not get any feedback, there is not much we can do. 

We requested the tc to review the documents, all the input came about
after the docs were published. I realize that there were some regression
bugs due to using OpenOffice format, but the editorial issues could be
easily incorporated if they were brought upon. 

I recommend you asking the tc to send comments earlier instead of
waiting for after the fact. This includes you Marc. I just saw that you
posted editorial issues to the tc's list, just now. 

I suggest us to work in pairs to improve the quality of the document,
which would be a good thing but keep changing the second pair of eyes
for each release. This will catch issues with a fresh look since there
are several of us. 

--umit
 

> -----Original Message-----
> From: Marc Goodner [mailto:mgoodner@microsoft.com] 
> Sent: Tuesday, Nov 08, 2005 3:05 PM
> To: Gilbert Pilz; ws-rx-editors@lists.oasis-open.org
> Subject: [ws-rx-editors] Improvements to our editorial workflow
> 
> Retitling...
> 
> I've already filed an issue to fix these and the other 
> editorial issues
> that came up in the CD. 
> 
> I'm raising this to point out that we need to adopt some of the
> proposals that have been made to improve the checks we need 
> to give each
> other before important drafts like a CD are published to the TC. 
> 
> The number one improvement I would suggest is that we not publish a CD
> before someone, not the last one to work on the doc, takes a pass over
> it.
> It's better to wait another week to get the CD to the TC so 
> that we can
> make sure it is of high quality than let these types of 
> errors through. 
> 
> You took on the work to prepare the CDs and asked all of us to provide
> you feedback on them (which is a lot less work than what you took on).
> To the best of my knowledge none of us was conscientious enough to get
> back to you before the docs were posted. While I appreciate wanting to
> get the CDs out before the following call I think their 
> accuracy should
> take precedence.
> 
> We can see this as a test run since there wasn't a call for public
> review. If I'm not mistaken there will be for the next one. We need to
> make sure we improve our process to catch issues like this before that
> CD gets released.
> 
> -----Original Message-----
> From: Gilbert Pilz [mailto:Gilbert.Pilz@bea.com] 
> Sent: Tuesday, November 08, 2005 1:32 PM
> To: Marc Goodner; ws-rx-editors@lists.oasis-open.org
> Subject: RE: [ws-rx-editors] RE: [ws-rx] Editorial issues with WD 05
> 
> Let's fix 'em in wd06 and move on.
> 
> - g 
> 
> > -----Original Message-----
> > From: Marc Goodner [mailto:mgoodner@microsoft.com] 
> > Sent: Wednesday, November 09, 2005 4:39 AM
> > To: ws-rx-editors@lists.oasis-open.org
> > Subject: RE: [ws-rx-editors] RE: [ws-rx] Editorial issues with WD 05
> > 
> > Not a single one of these made it into the CD (other than the 
> > status stuff that changed anyway). I don't think these should 
> > have required an issue to get addressed in the CD. Perhaps 
> > the multiple definition one, but the other ones are clear 
> > editorial mistakes. A whole lot more were introduced between 
> > this draft and the CD.
> > 
> > -----Original Message-----
> > From: Marc Goodner [mailto:mgoodner@microsoft.com]
> > Sent: Friday, October 14, 2005 3:18 PM
> > To: Anish Karmarkar
> > Cc: ws-rx-editors@lists.oasis-open.org
> > Subject: RE: [ws-rx-editors] RE: [ws-rx] Editorial issues with WD 05
> > 
> > And another thing, receive is defined twice (and differently 
> > each time) at lines 237 and 246.
> > 
> > -----Original Message-----
> > From: Marc Goodner [mailto:mgoodner@microsoft.com]
> > Sent: Friday, October 14, 2005 12:58 PM
> > To: Anish Karmarkar
> > Cc: ws-rx-editors@lists.oasis-open.org
> > Subject: RE: [ws-rx-editors] RE: [ws-rx] Editorial issues with WD 05
> > 
> > Sorry, 4 below is more wrong than I thought. After line 3 and 
> > before line 4 Document Identifier exists on the first page as 
> > a title and with no line number. That should be after a page 
> > break and line 4 should be
> > wsrm-1.1-spec-wd-05 with 05 probably being whatever the next 
> > revision number is. Also I guess this means line 60 should 
> > say WD right?
> > 
> > -----Original Message-----
> > From: Marc Goodner [mailto:mgoodner@microsoft.com]
> > Sent: Friday, October 14, 2005 12:42 PM
> > To: Anish Karmarkar
> > Cc: ws-rx-editors@lists.oasis-open.org
> > Subject: [ws-rx-editors] RE: [ws-rx] Editorial issues with WD 05
> > 
> > Here are some other editorial issues I've found by line number.
> > 
> > 4 Still identified as ED draft
> > 60 Shouldn't that be CD?
> > 184 extra space between accurately and determine
> > 187 The capitalized incorrectly, should be the
> > 633 Why does this line start with OPTIONAL? Any other 
> > optional elements/attributes are called out in the immediate 
> > line after they are declared. Furthermore I'm not sure this 
> > is optional, it is an extensibility point and as such I don't 
> > think anyone is supposed to barf if it is used. Earlier in 
> > the spec it clearly says unknown extensions should be ignored.
> > 1141, 1155, 1159, 1160 undefined namespace prefix of ws is 
> > used, should be xs
> > 
> > Not sure if I'll get to the policy doc today or not, I'll try.
> > 
> > -----Original Message-----
> > From: Anish Karmarkar [mailto:Anish.Karmarkar@oracle.com]
> > Sent: Tuesday, October 11, 2005 11:22 PM
> > To: wsrx
> > Subject: [ws-rx] Editorial issues with WD 05
> > 
> > All,
> > 
> > The editors would like to point out three ed issues against 
> WSRM WD-05
> > [1]:
> > 
> > 1) The pages numbers in the 'Table of Contents' aren't 
> > correct. OO requires that all the indexes be regenerated once 
> > changes are accepted, before generating the PDF. That was not 
> > done before generating the PDF at [1].
> > 
> > 2) There was a editorial regression. Line 678 in [1] says:
> > "to the element.Faults"
> > This really should be:
> > "to the element." and "Faults" should be on a new line and 
> > formated as a
> > 
> > separate section (section 4). Because of this regression, 
> > subsections that were previously subsections of section 4 are 
> > now subsections of 3 instead.
> > 
> > 3) Robin Cover pointed out an editorial bug on line 124. 
> > Given that our NS ends with a trailing '/' 
> > (http://docs.oasis-open.org/wsrm/200510/),
> > line 124 should be:
> > "reliable messaging namespace URI concatenated with the"
> > instead of:
> > "reliable messaging namespace URI concatenated with the "/" 
> > character and the"
> > 
> > -Anish
> > --
> > 
> > [1]
> > http://www.oasis-open.org/apps/org/workgroup/ws-rx/download.ph
> > p/14785/ws
> > rm-1.1-spec-wd-05.pdf
> > 
>