Re: [soa-rm] Proposed Role Descriptions for SOA-RM Editors

[Thomas Erl <terl@serviceorientation.org>]

Matt,

I would not focus on the quantity of pages in the reference model document, 
as this is not a suitable indicator of the effort required to achieve a 
quality specification.

Thomas

----- Original Message ----- 
From: "Matthew MacKenzie" <mattm@adobe.com>
To: <soa-rm@lists.oasis-open.org>
Sent: Wednesday, March 23, 2005 8:50 AM
Subject: Re: [soa-rm] Proposed Role Descriptions for SOA-RM Editors


> Rebekah,
>
> I don't think that the RM will contain much more than 35-40 pages of text, 
> so it may be that your excellent suggestion is a tad heavy for this 
> project.  In fact, I have some reservations about the number of editors we 
> have given the relatively small work product.  I'm concerned that the 
> document will inadvertantly become bloated with everyone trying to make 
> their mark.
> Of course...as one of the TC's initial proposers, I am overjoyed with the 
> amount of interest and enthusiasm everyone is showing toward this work.  I 
> just do not want to lose the original "reference model" focus.
>
> -Matt
> Metz Rebekah wrote:
>
>>All -
>>The recent discussion on editorial responsibility is one of the reasons
>>that I asked during the TC about document deliverables taking the form
>>of a single document versus a document suite.  For example, in the SAML
>>TC the 2.0 deliverable set was composed of 8 different documents.
>>Individual documents could be edited by a single editor for version
>>control purposes.  Taking a document suite approach avoids issues
>>regarding alignment of the master document update schedule to the
>>development schedule for individual sections.  I can imagine that at
>>some point, it will be time for an update to the master document but a
>>particular section would need another couple of days to be in a
>>consistent state.  The TC would then need to spend time thinking about
>>whether to hold off on the master document update or how to handle the
>>lag.  Maintaining a documentation suite sidesteps this problem.
>>Moreover, the approach also provides a springboard to logical naming
>>scheme which isn't based on section numbers in the master document.  For
>>example, what happens if, during development, it becomes apparent that
>>the sections should be re-ordered?
>>For my 2 cents, I think that structuring a document approach to minimize
>>the amount of inadvertant version control issues (and editorial
>>headaches) is time well spent.
>>Rebekah
>>
>>
>>
>>>-----Original Message-----
>>>From: Matthew MacKenzie [mailto:mattm@adobe.com] Sent: Wednesday, March 
>>>23, 2005 9:10 AM
>>>To: Rich Salz
>>>Cc: soa-rm@lists.oasis-open.org
>>>Subject: Re: [soa-rm] Proposed Role Descriptions for SOA-RM Editors
>>>
>>>Rich,
>>>
>>>You're right that someone has to drive, maybe we should just rotate 
>>>responsibilities.  It sure would be nice to have perforce, cvs or 
>>>subversion available to us.
>>>
>>>I think we just need a process, and here is what I am thinking:
>>>
>>>1. One person "drives" the task of developing the specification outline. 
>>>By drive, I mean, commits the outline to a document and revises based on 
>>>TC consensus.
>>>2. Parallel to the outline development, editing team decides on document 
>>>format and process, develops prelim schedule.
>>>3. Outline potentially becomes a "master document" -- 
>>>containing the ToC and boilerplate stuff.
>>>4. Work from the outline is split up, individual editors work on their
>>>chunk(s) of work and keep them updated in Kavi using some kind of naming 
>>>scheme (e.g. s1_Introduction.(doc|xml)) 5. Master spec custodian (1 month 
>>>shifts?) integrates individual chunks to the master specification every 
>>>2-4 weeks, and issues a "draft" for general consumption.
>>>
>>>That's my idea of how this should go.
>>>
>>>-matt
>>>
>>>On 23-Mar-05, at 8:59 AM, Rich Salz wrote:
>>>
>>>
>>>>>In fact, I am not in favor of having multiple "editors".  I am, 
>>>>>however, all for having multiple "authors".
>>>>>
>>>>Conventionaly, the WG members are the authors, and those
>>>who do most
>>>>of the text management, often incorporating directly text sent from the 
>>>>WG, are the editors.
>>>>
>>>>As for the "chief" question, I propose the editors work it
>>>out amongst
>>>>themselves.  I'll offer the suggestion that there should always be 
>>>>someone "in charge" so everyone has the clear expectation as to who owns 
>>>>the definitive copy.  This *will* come up; someone
>>>will ask "is
>>>>that in the latest draft", and it will be frustrating to have email from 
>>>>n-1 editors saying "I didn't do it" and the n'th say
>>>"yes", or,
>>>>more likely, "was that my task?" Perhaps it should rotate on some basis. 
>>>>Or if there are multiple documents, divide accordingly.
>>>> /r$
>>>>-- 
>>>>Rich Salz                  Chief Security Architect
>>>>DataPower Technology       http://www.datapower.com
>>>>XS40 XML Security Gateway
>>>http://www.datapower.com/products/xs40.html
>>>
>>>
>