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" <>
To: "Thomas Erl" <>
Cc: "Rich Salz" <>; <>
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" <>
>> To: "Rich Salz" <>
>> Cc: <>
>> 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
>>>>
>>>
>>
>>
>
