Hi, I've got a couple of doc nitpicks from a "beginner" perspective:
(1) Could the Dictionary *please* have "Related Words" sections added to the entries for both the monadic and dyadic forms of words? There could be one related or several related words--or perhaps no related words. I'm thinking primarily in terms of cross references to related words (for example, box/ace) or to opposites and inverses (for example, take/drop, box/open, square/square root, infinity/negative infinity)-- of course, these should be hotlinked in the online version. As a beginner, I have the darndest time trying to find related terminology. The Dictionary seems to indicate *no* relationships between the words contained in it (that is, no "see also" references). Perhaps there are relationships, but they certainly do not seem at all intuitive to a new user. (I'm aware, of course, that there is a relationship between inflected forms, but that symbolic relationship is not always obvious in the terminology used.) (2) The Dictionary (at least its PDF print version) needs two major additions to its indexing: (a) the terms currently used may be quite exact, but many of them are not the first word that may come to mind for the concept involved; the index of words needs to include additional alternative English words for some of the terms chosen as well as inverted forms (that is, both "natural logarithm" and "logarithm, natural")--a good index has *lots* of entries; and (b) an "alphabetical" index of the primitives in ASCII order for quick assistance to new users in figuring out sequences of verbs, etc., found in published scripts, electronic books, documentation resources, and forums. (I've had to create such indexes for my own learning purposes, but I don't think new users should have to do that for themselves.) The "Ndx" does fine with alphabetical entries, but there's plenty of room along the top of the page to include the punctuation symbols as well. To truly be a "master" index, it should include the "base" symbols; the inflections would be included under each base symbol. Curiosity question: how come the ijt and ijs entries in "Ndx" aren't hotlinked? (3) EXAMPLES! EXAMPLES! EXAMPLES! Advanced users can easily get by (that is, "Oh, I see!") with only a single example or two, but new users need lots more. This is by far the most common complaint among new users of *any* software, whether application, language, or whatever. What I think is needed is an additional "Dictionary of Examples", where there might be, say, 10-15 examples for each verb, adverb, control, foreign conjunction, etc. These examples would use "real" data (that is, avoid the iota/integers generator), both numeric *and* textual, and would illustrate all sorts of cases where this verb (etc.) might be practically used. Perhaps there might be a separate "dictionary" of examples for the verbal commands in the "Definition Summaries" (such as wd, gdbmp, colhdr, rplc, etc.) What would also be extremely useful for newer users is a small collection of "real world" type application script examples that would have *extensive explanatory commentary*. I'm not looking here for multi-hundreds of lines of code (which I guess, based on forum messages, is what sophisticated commercial application scripts must seem to have), but for simple scripts that might be up to, say, 20 to 50 lines that illustrate a self- contained "mini-application" (even something as simple as reading a disk file, massaging the data in some way, and writing the revised data back to disk--this is a basic operation that is fundamental to most or all other application scripts). The forums and such provide lots of elegant single-liners and such, but there's little about the preferred method(s) of creating application scripts: what should be at the head of the script, how to arrange code for best understanding and maintenance, and what code and cleanup should be at the end of the script. (4) All online documentation should also be available in PDF files. (Some is, some isn't; some current PDF's may be official, some may be "unofficial".) There should be "Print PDF" buttons associated with each online document. (5) I'm a librarian, but I was a former (35 years ago) elementary school teacher and have done some teaching at the college and adult level, too. These experiences reinforced for me the values of simplicity and clarity in the learning process. The current problem with J is that, with all the current documentation and such, one jumps into the middle of the language. There is no real "beginning" aspect for brand-new users. Because J requires a paradigm shift in thinking (compared with other programming languages), I feel that it is absolutely necessary that J have a new additional set of documentation designed specifically for "beginners" that takes things "slow and easy". Much of the content could, of course, be derived from some of the current documentation--just re-worded, re-phrased, and simplified, with lots of examples. By the way, if anything above is misphrased or seems to be a misunderstanding of J, please remember that I'm a beginner to J, and I'm still learning little by little as I have opportunity. There has been discussion about making J more widely known and used. I think that "new user helps" along the line of what I described above could be useful towards reaching that goal. Harvey ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
