The example I showed at the meeting is at http://www.perlmonks.org/?node_id=280658 . What I liked about this example is that an idiom is broken down for explanation, then the comments illuminate how people have found this expression to be useful and what they see as its limitations. This is the sort of thing for which a wiki is well-suited.
Personally, I find specific examples of how an idiom or primitive is used in practice to be the most helpful form of explanation - YMMV. I put up a vocabulary page at http://www.jsoftware.com/jwiki/Vocabulary but the wiki does some funny things to a few of the entries. On Fri, Jan 15, 2010 at 8:25 AM, Devon McCormick <[email protected]> wrote: > 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/<http://www.cs.mcgill.ca/%7Eabatko/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 > > -- Devon McCormick, CFA ^me^ at acm. org is my preferred e-mail ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
