How about 'J usage for Ordinary Mortals'? Many great ideas have been expressed in this thread, but IMHO what is really needed is a J equivalent of that introductory APL classic by Gilman and Rose. A reading of Gilman and Rose took me from knowing nothing about APL to a career development path based on APL. If the objective is to ease the barriers to entry into the world of J and grow and diversify the J user base then I can think of no more productive approach than making a 'Gilman and Rose' type of text available.
While I am at it I might as well add that I also feel quite strongly that a lot could be done to make the existing HTML documentation more accessible and useful through some judicious restructuring, and/or through some liberal application of hyperlinking. -----Original Message----- From: [email protected] [mailto:[email protected]] On Behalf Of Dan Bron Sent: Saturday, January 16, 2010 7:10 AM To: 'Programming forum' Subject: Re: [Jprogramming] The Ambiguous Dictionary (Sorry, there's something wrong with my mail client tonight, it keeps sending messages before I complete them.) > 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, and we'd like it accessible but not still not bulky, and concentrating on a few common uses will definitely clarify those common uses, but it will do so by dispensing with irrelevant detail (to those uses), 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. We could have a "glossary" we could link to, so we could still use technical terms, e.g. "frame" or "fill", and not expand on them in every entry, but not leave the user scratching his head at their meaning, either. and regarding Henry's suggestion: > it would be fabulous if the Wiki pages initially contained the > full text from the Dictionary. We could also link to the definitive DoJ entry, without having to reprise it (or keep it up to date), and still allow users to rely on Dictionary2 with complete confidence. Of course we can quote and comment upon relevant parts directly in the page. Anyway, Devon has started the effort at http://www.jsoftware.com/jwiki/Vocabulary . Interested parties can start creating Vocabulary2 entries as subpages of that. Maybe Harvey could get the ball rolling by just pasting in his existing write-ups. -Dan PS: We need a better name for this project. Dictionary2, Phrases2, Vocabulary2, etc are clunky (plus these efforts aren't really new superceding versions, but parallel texts with different goals). I like Henry's "Wiktionary" but that name is already taken by a more famous project. I'd suggest "DoJ for Dummies" because their motto is "A reference for the rest of us", but "for Dummies" is condescending. Ideas? ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm No virus found in this incoming message. Checked by AVG - www.avg.com Version: 9.0.725 / Virus Database: 270.14.142/2623 - Release Date: 01/16/10 21:35:00 No virus found in this outgoing message. Checked by AVG - www.avg.com Version: 9.0.725 / Virus Database: 270.14.142/2623 - Release Date: 01/16/10 21:35:00 ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
