OK, everybody got it that attaching keywords to any and all J documentation is suggested. Now, how to go about it practically?
--- Skip Cave <[EMAIL PROTECTED]> wrote: > In his post, Harvey gives examples where he shows where the keyword > tagging of information is critical to the learning experience. As I have > mentioned in earlier posts, beginners and casual users have a very > difficult time finding how to build the functions that they want in J. > This is primarily because the names that the neophyte might commonly > enter into a search engine to find a specific function or example, is > simply not in J's documentation. As Harvey explains in his post: "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")" > > I know from direct experience, nearly 2/3rds of the time, the > functionality I seek in the documentation can't be found because of > missing terminology. The functions I need are almost always there > somewhere, I just can't find them. This isn't an indexing problem. The > J Ndx and the Google domain search does a fine job of indexing. This is > a semantics problem. The words used by the searcher aren't the words > used by the author. > > If the user finally does find what they are looking for (often by > posting a request to the forum), it should be standard procedure for the > user, or the person who answered the users question, or the author, to > add the keywords that was used to ask about the function, to the > documentation for that function. In this case, Harvey talks about the > PDF version of the Dictionary in his post, so this isn't a wiki issue. > > I am convinced that even though J is a powerful, general-purpose > language, it will stay a specialist's tool, as long as this reference > problem isn't solved. The paradigm shift required to grasp the basic > concepts of J (or APL) is a significant barrier. Much of this barrier is > simply the lack of common semantics between the learner and the > documentation. Today, only the truly dedicated are willing to expend the > energy to overcome this barrier. > > Information on J comes in many forms; PDF documents, Forum posts, Wiki > pages, MS Word docs, HTML docs, and more. Search engines have solved the > problem of indexing all of these kinds of documents into a single index, > allowing a single search to find keywords and return documents in all of > these formats. The problem we face is the inverse of that - how to allow > a neophyte user to add keywords (tags) to all of these formats so that > it gets put into the search engine. Like the search process, a single > simple step should allow a user to tag keywords onto the information he > finds. Ideally, the find and tag operations could be performed in the > same process. > > So that is the challenge for J, if it wants to truly expand its user > base. Some out-of-the-box brainstorming may be required to come up with > the solution.... > > Skip. > . > . > . > > PackRat wrote: > > 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 > > > > > > > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > ____________________________________________________________________________________ Never miss a thing. Make Yahoo your home page. http://www.yahoo.com/r/hs ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
