I think Dan has hit upon a key point. There are two major classes of users of the Vocabulary and Dictionary. There are expert users, who need a concise reminder of the operation of a primitive or common function. The current Vocabulary and Dictionary are excellent reference documents for this target audience.
However, there are also new users, or occasional users who tend to forget things (I'm in this group) who are looking at a primitive, or some common function and want an explanation of a specific primitive, digraph, or other construct. I can tell you from personal experience, that the Vocabulary definitions are practically useless to this second type of user. It takes some while to understand enough of the language to be able to decipher the "code" used in the Vocabulary document. The Dictionary is a bit more verbose if you can find the topic you want, but the terminology used by the Dictionary (and J experts) is still pretty esoteric to the non-expert ear. 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, and read to the end. The rationale is that many new users don't necessarily want to read through "J for C" or "Learning J" to "kick the tires" with a language. They might have stumbled across J on the Rosetta Code site, or in some other context, and just want to look up a primitive in some example. I suspect that more people approach a language in this way, rather than taking the formal approach of reading an introduction document , and then proceeding with a planned lesson sequence. So the "training wheels" mode is STILL A REFERENCE MODE, where users see a J sentence, and want to understand what it is doing, by looking up each symbol, one-by-one. However, in the training wheels mode, each vocabulary description should stand alone, making 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. This structure would likely do more to advance the understanding (and usage) of J than almost any other project, assuming that is a goal you would like to achieve. Skip Cave Dan Bron wrote: > Without taking a stance on the issue (I'm not sure where I stand), I will > note there are types of writing and writers who try to eliminate redundancy > to the extent possible, and this is seen as a virtue. For example, > mathematical proofs (IIRC), and for that matter, programming. > > There are also (different) types of writing and communicating where > redundancy is intentional and typical. One could argue dictionaries fall > into this category (where a definition is often described with multiple > synonymous terms and some examples). Critical communiques are also often > redundant (but not always re-expressive, which warrants attention). > > Then again, most of us ask for more redundancy in the DoJ when we're learning > the language, and find it fine as it stands once we already know what it > means (aka are already fluent in the language). > > Ken would have been the first to (emphatically) tell you that he did not > intend the Dictionary to be used as a tutorial, but rate) her a reference, > which is in accord with the previous paragraph. He wrote other material to > be used as tutorials (and pioneered the use of those interactive tutorials, > the Labs). And several others have supplemented this external (to the DoJ) > learning material. > > -Dan > > PS: If I ever finish the PrimitivePrimitives project, it could be a basis > for an alternative, highly redundant Vocabulary. And I would not be too > surprised if some of the entries made it into the examples sections in the > true Vocab. After all, they would be J code, not redundant (competitive to > the normative) English, and the examples are already (purposefully) redundant. > > The project itself would be redundant to the Dictionary :) > > > Please excuse typos; composed on a handheld device. > > -----Original Message----- > From: Jose Mario Quintana <[email protected]> > Date: Thu, 14 Jan 2010 10:25:16 > To: Programming forum<[email protected]> > Subject: Re: [Jprogramming] The Ambiguous Dictionary > > In my opinion R.E. Boss’ point still stands (notwithstanding what Wikipedia’s > value as a general source of reference might be from one’s point of view). > What can be sufficiently clear to the writer might not be to the reader and > redundancy (from the author perspective) could clarify the exposition of > difficult concepts (from a reader’s viewpoint). > > Extra explicit statements in the dictionary such as "adverbs and conjunctions > cannot take adverbs or conjunctions as arguments" or "a fork does not have > any other implied order-of-execution apart from the diagrams" can or could > have been helpful as far as I am concerned (so, in the latter case, even the > best of the readers would not have to guess the original intention ( > http://www.jsoftware.com/pipermail/programming/2007-December/009118.html ). > > > > > ________________________________ > From: Raul Miller <[email protected]> > To: Programming forum <[email protected]> > Sent: Wed, January 13, 2010 8:31:56 AM > Subject: Re: [Jprogramming] The Ambiguous Dictionary > > On Wed, Jan 13, 2010 at 2:18 AM, R.E. Boss <[email protected]> wrote: > >> From http://en.wikipedia.org/wiki/Redundancy_(language) >> (capitals from me, REB): >> > > And we all know that the wiki is always completely > accurate. > > ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
