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


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



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