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

 


Help: OASIS Mailing Lists Help | MarkMail Help

soa-rm message

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


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


I did not indicate that a focus on document size was envisioned.

I just stated my own prediction.

-Matt
Thomas Erl wrote:

> 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
>>>>
>>>>
>>
>
>



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