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

[Subbu Allamaraju <subbu@bea.com>]

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>