> Anyway, Devon has started the effort at > http://www.jsoftware.com/jwiki/Vocabulary .
Spot-on. I'd like to be in on this. And I have one clear advantage over you all ... (*preen-preen*) ... I'm a genuine Beginner! :-P Seriously though, I'm worried that (without a human factors lab to test it in) we could all conspire to build something beautiful -- and useless. That said, the starting point has to be Devon's http://www.jsoftware.com/jwiki/Vocabulary . Each cell, I take it, will be clickable, leading to a page for the primitive in question, with links pointing off in all directions. These can be lovingly contributed by readers as time goes on. Some mention of the really useful cover-words in the 'z' locale, plus extra ones (would you believe I have and=:*. and: or=:+. because I mix them up?) An illuminated primitive at the top (why should APLers have all the fun). And a great big colon halfway down to separate monadic and dyadic usage. Observing myself at work, my main point-of-entry is Voc. Even though when I click a link I'm confronted with a page of dense, arch detail which mostly washes over my head. But that's because it's full of my immediate problem, with no spare capacity to go decyphering tablets of stone. The remedy, I think, is simple. Code examples. Easy ones: the existing Voc ones are far too fussy. It's as if the writer was ashamed of offering something too trivial and so being thought a fool. But an example cannot be too trivial: it's only got to work. As you gaze at the page in a red fog of concentration, there should be a code line so easy you can never fail to adapt it to work in the context of your white-hot ijs-page, and lather it up from there. Not a lot of examples either. IMO three or four at most. I've been an early user of scores of experimental language processors They've all come with reference material written by the implementer: stylised, precise, dense, lean, mean and totally opaque. What has worked best for me and others is where users have contributed them. Actual ones they were seeking to cast light upon. The simpler the better. Generic of course. The reference manual for Burroughs Algol was a perfect example. It was the only thing people ever used. When someone left the company the manual vanished too. Everything was in Bachus-Naur Form (BNF), which you just skipped over, unless you were thoroughly into forensics and about to report a compiler bug. But down at the bottom were three clear simple lines of Algol, never more, never less -- and they answered every question in your head. They had the hallmarks of being contributed by users, not the scribes. Ian On Sat, Jan 16, 2010 at 5:10 AM, Dan Bron <[email protected]> wrote: > (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 > ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
