We discussed this at NYCJUG this week - I offered some examples of how explanation for beginners is better done: one is the old APL reference by Sandra Pakin, another is an example in Perl - I can't find the example I used right now but search on something like "perl key" or see http://www.cs.mcgill.ca/~abatko/computers/programming/perl/howto/hash/ or http://www.devdaily.com/perl/edu/qanda/plqa00015/ .
The Perl example I showed was good because it allowed user responses to elaborate on the explanation and examples shown. The Pakin reference manual was useful because it has a definition on one page and some examples on that page and the facing page. On Thu, Jan 14, 2010 at 6:23 PM, Dan Bron <[email protected]> wrote: > Skip Cave wrote: > > What is needed is a "training wheels" mode where each Vocabulary entry > > has lots of examples, common usages, explanations of terms, etc. Same > > for the Dictionary, which should explain each definition as if the user > > has not read anything about J before this instant (which will often be > > the case). This is for the reader who doesn't start at the beginning, > > Ah, ah. I think you have struck the heart of the matter. There is a J > user base who finds the Dictionary's terseness an impediment (I did for a > very long time), and another who find it a benefit (like I do currently). > > The insight is that the former group turn to the Dictionary, because that > is the only reference they have. If they didn't have to read the > Dictionary, they wouldn't. If they had somewhere else to turn, they would. > If this group had another option, the DoJ's terseness would be irrelevant. > > If we consider Skip's idea in the light of Raul's earlier question: > > > Is there some kind of problem with tutorials and other works > > providing this level of redundancy? > > we realize that it is not incumbent upon JSoftware to provide this option. > Their job is to publish the normative reference for the language and the > official implementation. And that's what they spend their time doing > (thanks!). > > So someone else must furnish the verbose alternative Dictionary. I note > that those who want it, are in exactly the wrong position to provide it. > I further note that the community (this community) has often furnished > itself with related material (labs, books, demos, the Wiki). So there's > the gauntlet, on the ground... > > -Dan > > PS: Maybe we could do this communally, rather than burdening an > individual. If I started a Wiki area that was formatted like the > Dictionary, and maybe created a seed Vocab entry or two, would others > contribute to completing it? > > Remember that the goal is still to create a reference, not a tutorial. So, > for example, we'd have an entry on cut, but not on parsing strings (though > we could link to other parts of the Wiki for this). The entry would have to > describe what cut is, and all its subtleties, in an accessible way, but not > how to use it. Each entry must attempt to be both complete and correct > (though still deferring to the real DoJ in the case of any conflict). I'm > not sure this would be an easy thing to do, so it's worth considering before > you commit to the project. > > Also worth considering is that the value of a reference is not a linear > function of its completeness. A 25% done Dictionary is not 25% as valuable > as a completed Dictionary, because if you can't trust it, you won't turn to > it in the first place. Furthermore, community projects also have this "non > linear" aspect, and if this isn't a very visible project with lots of > activity, newcomers won't know about it, and veterans won't contribute to > it, and it will die, and we'll be back in the same boat. > > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > -- Devon McCormick, CFA ^me^ at acm. org is my preferred e-mail ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
