Re: [wsrp-primer] Proofread v0.61-edit-rex

[Rich Thompson <richt2@us.ibm.com>]

We had a similar occurrence when producing
the spec ... it suddenly shot from 1MB to 11MB without any particularly
identifiable reason. Accepting all (or as many as possible) changes before
saving it into a new document usually causes whatever has caused the bloat
to go away.                
       

Rich

Rex Brooks <rexb@starbourne.com>

07/21/2004 12:22 PM

To	Subbu Allamaraju <subbu@bea.com>, wsrp-primer@lists.oasis-open.org
cc
Subject	Re: [wsrp-primer] Proofread v0.61-edit-rex

Thanks Subbu,

If you do a "Save as" using the same name, it usually incorporates
all the changes in a virtually new document and that cuts down on the 
size. It also helps to accept all changes before doing that and that 
cuts down on carrying all of the previously tracked changes into the 
"Saved as" version. I'm not sure that has anything to do with
the 
sudden jump in size, but it should cut down on final size.

Ciao,
Rex

At 8:25 AM -0600 7/21/04, Subbu Allamaraju wrote:
>Rex,
>
>Thanks for the corrections. My response below to your 
>comments/suggestions. I'll post the draft as soon as I figure out 
>why the doc suddenly shot up from 800k to 8mb, even after removing
>hidden data.
>
>Regards,
>
>Subbu
>
>Rex Brooks wrote:
>
>>Hi Folks,
>>
>>Please note that I am just attaching my pass through v0.61 rather
>>than uploading it. I don't think we need another document for this
>>little piddling stuff.
>>
>>For 95 percent of the Primer, I did plain vanilla proofreading.
I 
>>changed the word "Besides" twice where it started sentences
because 
>>it sounded funny to me, using "Other than... " and "In
addition 
>>to... ." Since this is just my take on it, you are free to
include 
>>those and a couple of other word changes or not. Some very few
>>constructions just seemed awkward to me.
>>
>>Mostly I just ran into typos, missing words like "to"
and "the" and 
>>missing or extra plurals for agreement. It is impossible when 
>>reading something this large for me not to actually think about
>>some specific things, so... take the following with a large grain
>>of salt and please understand that this is mostly just what I will
>>be thinking about and probably will ask about in the F2F to get
>>more feedback on what the best mix will be. I sure don't claim
to 
>>know at this point.
>>
>>While proofreading, although I did not make the changes below,
I 
>>ran across the following:
>>
>>-----------------------------------
>>In the  Basic Scenario section of the Introduction:
>>
>>(g), (h), and (i) may be a little confusing for the reader. 
>>Currently there is nothing that indicates how the Producer tells
>>the Consumer that the user interaction has been processed before
>>the Consumer sends a request to get the changed markup. In (h)
the 
>>Producer conducts a performBlockingInteraction but it is not 
>>described as such because we are trying to symplify our description
>>of the process in the introduction. (This is described in the 
>>following paragraphs, so the reader finds out quickly what actually
>>happens.)
>>
>>So, the sequence might be easier to understand for the reader at
>>that point in the introduction stage if the sequence goes like
this:
>>
>>(g) C Inc. receives the request containing the form data submitted
>>by the user. Upon determining that this request is meant for the
>>portfolio management application, C Inc. sends another request
to P 
>>Inc. to process the user interaction.
>>(h) P Inc processes the user interaction request, adds the sticker
>>symbol to the user's portfolio, and returns new current state of
>>the portfolio.
>>
>>(i) C Inc then sends a request to get the changed markup based
on 
>>the new current state of the portfolio. P Inc generates markup
and 
>>returns.
>
><subbu>Incorportaed your suggestion.</subbu>
>
>>While this is still not an exact representation of what does 
>>happen, it doesn't leave a gap where the reader has to ask 
>>themselves how the Consumer knows when the Producer has processed
>>the user interaction and it is still more simple than if we were
to 
>>introduce the performBlockingInteraction concept before the 
>>subsequent paragraph (b) Markup Interface. And it avoids bringing
>>up the issue of whether the Consumer can markup contained in the
>>performBlockingInteractionResponse versus a new getMarkup call.
>>
>>-----------------------------------
>>In 4.1
>>
>>in the last sentence of the first paragraph, I don't think the
word 
>>'scope' is well enough understood as a verb to use in this context,
>>so I suggest the following rewrite: "Note that the purpose
of the 
>>registration is not to uniquely identify a Consumer but to 
>>establish a scope for a Consumer's use of a Producer."
>
><subbu>Incorportaed your suggestion.</subbu>
>
>>-----------------------------------
>>In Markup Interface...
>>
>>Also, as a general note on the Markup Interface section, while
it 
>>reads much better and makes much more sense than it did before,
it 
>>now is substantially more detailed in what it explains than the
>>actual specification is, which shows how important it is to get
>>developer feedback on what is actually needed. The first two times
>>through this section, it really wasn't clear what was needed nor
>>how thoroughly it needed to be explained in addition to what is
in 
>>the spec itself. Now it may actually be more detailed than needed.
>>But it is very difficult to find a good balance. I think we are
>>probably going to need to edit out some of this section, but maybe
>>not.
>>
>>In 5.2.3 State Changes and Implicit Cloning, I suggest introducing
>>portletStateChange first as a way to allow the Consumer to indicate
>>its capabilities, then go on to explain why this adopted to allow
>>implicit cloning within performBlockingInteraction. The intricacies
>>seem likely to confuse newcomers if they are introduced first as
a 
>>way to explain why a Consumer needs to tell the Producer about
its 
>>capabilities.
>
><subbu>Added your comment to the draft.</subbu>
>
>>Remember, I am bringing this up because I will be thinking about
it 
>>for the F2F, so just to be perverse, and contrary, if we are going
>>to discuss navigationalState and URLs in detail, shouldn't we also
>>describe how templates work, since we mention them?
>
><subbu>Good point. Let's see what TC feels about it? I've added
your 
>comment to the draft</subbu>
>
>>Same thing with User Profiles and Categories. (I'm still working
up 
>>to a discussion of this. It's complicated and I don't want to start
>>something on the wrong foot so to speak.)
>>
>>-----------------------------------
>>In Use Profiles, the column headers need to be bold and repeated
>>whenever a page break occurs. Also, for readability the alignment
>>within the columns should be set to align left, not justified.
On 
>>page 41 at the top, in the Notes column the entry saying "P
Inc 
>>uises in-band registration does not appear to connect to anything
>>and such specific references don't occur elsewhere in the table.
So 
>>it should probably be deleted.
>
><subbu>Replaced with Clinton's updates in the new draft.</subbu>
>
>>It's really amazing how this has managed to come together. I take
>>my hat off to you Subbu.
>
><subbu>Thanks Rex.</subbu>


-- 
Rex Brooks
GeoAddress: 1361-A Addison, Berkeley, CA, 94702 USA, Earth
W3Address: http://www.starbourne.com
Email: rexb@starbourne.com
Tel: 510-849-2309
Fax: By Request