[Dev] review of BuildingChandlerParcels

[Philippe Bossut]

Katie Capps Parlante wrote:

> Alec's doc is a more complete tutorial. By "like its style better", do 
> you mean that its more helpful to read a longer tutorial, or is there 
> some other concrete advice for the "building chandler parcels" doc's 
> style that might be helpful?

New notation, variable, packages, notion etc... should be explained or 
mentioned as soon as introduced. If nothing else, say "don't pay 
attention x for the moment" if explaining "x" would be confusing. If 
suppressing "x" from the code snippet would help readability, do so.
For instance feed_controller is not explained (the reader must assumed 
it's an instance of FeedController). I'd suggest to add where this 
instance is created.

> You mention Chandler-specific terminology, for example -- is your 
> point that terms are introduced before they are explained?

Yes, SuperKind is used but not defined for instance. I'm not even sure 
what SuperKind is (the text says "you noticed that Feed Item has a 
SuperKind" but that's actually the first time in the text that the 
concept "SuperKind" is used so it's unlikely that a reader would have 
noticed it). FWIW, I just considered that SuperKind was the parent Kind 
class of a Kind (but I'm not sure this is true...). Since SuperKind is 
only used in this paragraph I think the notion should simply be 
suppressed in favor of the more classic class inheritence notion 
(assuming my understanding of SuperKind was correct...).

> Perhaps following Alec's earlier advice that the doc should just be 
> shortened would help (which I know Ted intends to do). This doc is not 
> meant to be a full tutorial, but one attempt to give the big picture 
> from a parcel writer's perspective, in a relatively short paper. 

Fair enough. There is space for both a short overview and a full blown 
tutorial. Ted's doc already points the reader to Alec's one for more 
info (right now it points back to the same doc but this has already been 
reported to Ted).

Cheers,
- Philippe