[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
Thomas, I don't think that a rewrite of the document will happen whenever custodial authority is passed to another individual. I think that the tone and style of the document will be established early on, and adjustments will be made during the draft->review->draft cycle. If the majority of the TC feels we need a single editor to act as style and scope guardian, I would hope that the final document would not attribute that individual any differently than the other editors. And yes, I feel the same way regardless of who this person is. -Matt 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 >>>>> >>>> >>> >>> >> > >
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]