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

[Frank McCabe <frank.mccabe@us.fujitsu.com>]

Matt, Thomas, etc...
  I think that what is at the heart of this is:
1. A chief 'editor' would help in bringing a unifying style.
2. Such a job is not lightly taken on
3. Project management is an essential factor in delivering a quality 
document in reasonable time
4. It seems premature and invidious to select such a person at this 
time (until we have gotten to know each other better)
Frank
On Mar 23, 2005, at 11:07 AM, Thomas Erl wrote:

> Matt,
>
> I don't think anyone is assuming that those who volunteered to 
> participate as editors have poor writing skills or lack the ability to 
> follow a plan. Individuals do, however, have different writing styles 
> and preferences. By rotating custodianship you subject the document to 
> these differences. How does this improve consistency?
>
> Thomas
>
> ----- Original Message ----- From: "Matthew MacKenzie" 
> <mattm@adobe.com>
> To: "Thomas Erl" <terl@serviceorientation.org>
> Cc: "Rich Salz" <rsalz@datapower.com>; <soa-rm@lists.oasis-open.org>
> Sent: Wednesday, March 23, 2005 10:44 AM
> Subject: Re: [soa-rm] Proposed Role Descriptions for SOA-RM Editors
>
>
>> You're right if you assume that a large percentage of the editing 
>> team have poor writing skills and are not capable of sticking to the 
>> overall documentation plan.
>>
>> I'm not familiar with most of the people who have signed up to become 
>> editors of this specification, so I am assuming (optimist that I am) 
>> that a chief cat herder / grammar coach will not be required.
>>
>> Consistency can be achieved by simply agreeing on format and tone.  
>> Daily at work I see hundreds of examples of this working in 
>> everything from source code to product manuals.
>>
>> -Matt
>> Thomas Erl wrote:
>>
>>> Matt,
>>>
>>> The SOA Reference Model we are about to put together will establish 
>>> abstract and foundation concepts upon which any number of 
>>> implementation specifications could eventually be based. The clarity 
>>> in which this document expresses these concepts is therefore, in my 
>>> opinion, extremely important. More so than in other technical 
>>> specifications that describe languages and implementation details, 
>>> concepts covered by this document must be defined clearly and 
>>> unambiguously.
>>>
>>> I believe that an informal or casual collaboration process could 
>>> jeopardize the quality and potential of this document. Typically, a 
>>> resource dedicated to pulling everything together will ensure that 
>>> content remains consistent throughout the TC process. I am doubtful 
>>> that consistency is improved by rotating custodians.
>>>
>>> Thomas
>>>
>>> ----- Original Message ----- From: "Matthew MacKenzie" 
>>> <mattm@adobe.com>
>>> To: "Rich Salz" <rsalz@datapower.com>
>>> Cc: <soa-rm@lists.oasis-open.org>
>>> Sent: Wednesday, March 23, 2005 6:09 AM
>>> 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
>>>>>
>>>>
>>>
>>>
>
>