[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
I did not indicate that a focus on document size was envisioned. I just stated my own prediction. -Matt Thomas Erl wrote: > 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]