Proofread v0.61-edit-rex

[Rex Brooks <rexb@starbourne.com>]

Title: Proofread v0.61-edit-rex

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.

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."

-----------------------------------
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.

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?

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.

It's really amazing how this has managed to come together. I take my hat off to you Subbu.

Ciao,

Rex

-- 

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

wsrp-primer-1.0-draft-0.61-edit-rex.doc