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 _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Open Source Applications Foundation "Dev" mailing list http://lists.osafoundation.org/mailman/listinfo/dev
