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

[Thomas Erl <terl@serviceorientation.org>]

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