> So there's the gauntlet, on the ground... Henry: > I would help. I think this is an important thing to do.
Harvey: > MOST CERTAINLY! Devon: > I put up a vocabulary page at http://www.jsoftware.com/jwiki/Vocabulary Awesome! Regarding format, I think I would like to stick with Skip's original idea: > The key idea here is that we are discussing a reference document > as opposed to a tutorial For several reasons: we are writing a Dictionary, we'd like it accessible but not still not bulky, and because concentrating on a few common uses will definitely clarify those common uses, but it will do so by dispensing with irrelevant detail, when what we want is a comprehensive definition which should cover all detail (and hence all uses, even if they're less common). That's not to say the entries won't contain examples -- even our concise existing dictionary contains examples. The new, verbose one will probably contain even more, with commentary. But this will be an ancillary feature. But I like Devon's idea and agree with this sentiment: > Personally, I find specific examples of how an idiom or primitive is > used in practice to be [a] helpful form of explanation So maybe we can have a separate, parallel "guide to J usage" (analogous to English usage guides, as the DoJ is analogous to an English dictionary); maybe this would be a verbose new Phrase book. And I too agree with James Foit regarding hyperlinking, and using links we can weave Dictionary2 and Phrases2 together: > I suspect that the most useful way for newbies to get more help for a specific primitive is to provide > a "more help" link from each Vocabulary2 entry to the tutorial wiki page for that primitive. > , each vocabulary description should ... make the assumption that the user reading the description does not know J, or know any of the terminology used in J. Hyperlinks could be used in the descriptions to help with ancillary definitions and other information. In fact, we can use links to address another concern of Skip's: we can interweave the uses at the expense of the more general tool. and But we can definitely have a separate "guide to J usage" -----Original Message----- From: programming-boun...@jsoftware.com [mailto:programming-boun...@jsoftware.com] On Behalf Of Devon McCormick Sent: Friday, January 15, 2010 10:38 AM To: Programming forum Subject: Re: [Jprogramming] The Ambiguous Dictionary 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 <devon...@gmail.com> 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 <j...@bron.us> 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 ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
