[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
Matt, I would not focus on the quantity of pages in the reference model document, as this is not a suitable indicator of the effort required to achieve a quality specification. Thomas ----- Original Message ----- From: "Matthew MacKenzie" <mattm@adobe.com> To: <soa-rm@lists.oasis-open.org> Sent: Wednesday, March 23, 2005 8:50 AM Subject: Re: [soa-rm] Proposed Role Descriptions for SOA-RM Editors > Rebekah, > > I don't think that the RM will contain much more than 35-40 pages of text, > so it may be that your excellent suggestion is a tad heavy for this > project. In fact, I have some reservations about the number of editors we > have given the relatively small work product. I'm concerned that the > document will inadvertantly become bloated with everyone trying to make > their mark. > Of course...as one of the TC's initial proposers, I am overjoyed with the > amount of interest and enthusiasm everyone is showing toward this work. I > just do not want to lose the original "reference model" focus. > > -Matt > Metz Rebekah wrote: > >>All - >>The recent discussion on editorial responsibility is one of the reasons >>that I asked during the TC about document deliverables taking the form >>of a single document versus a document suite. For example, in the SAML >>TC the 2.0 deliverable set was composed of 8 different documents. >>Individual documents could be edited by a single editor for version >>control purposes. Taking a document suite approach avoids issues >>regarding alignment of the master document update schedule to the >>development schedule for individual sections. I can imagine that at >>some point, it will be time for an update to the master document but a >>particular section would need another couple of days to be in a >>consistent state. The TC would then need to spend time thinking about >>whether to hold off on the master document update or how to handle the >>lag. Maintaining a documentation suite sidesteps this problem. >>Moreover, the approach also provides a springboard to logical naming >>scheme which isn't based on section numbers in the master document. For >>example, what happens if, during development, it becomes apparent that >>the sections should be re-ordered? >>For my 2 cents, I think that structuring a document approach to minimize >>the amount of inadvertant version control issues (and editorial >>headaches) is time well spent. >>Rebekah >> >> >> >>>-----Original Message----- >>>From: Matthew MacKenzie [mailto:mattm@adobe.com] Sent: Wednesday, March >>>23, 2005 9:10 AM >>>To: Rich Salz >>>Cc: soa-rm@lists.oasis-open.org >>>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]