I have no problem with Raul's suggestion that every vocabulary page provide links to the official reference page for a particular primitive or concept. It certainly doesn't hurt, and novices can simply ignore all the links they don't understand. For that matter, every standard vocabulary page should have a "more help" link to the TWV page for that primitive, as well.
I also agree with Oleg's comment that the vocabulary should target more than just the pure novice reader. The real issue is: just how do you do that? How can one explain a primitive or concept in such a way that won't bore the more experienced reader, yet cover the topic in the detail needed for a novice? The reality is, that you probably can't satisfy both extremes very well. However, the J documentation doesn't lack reference material for the intermediate and experienced readers. What we want here is a reference for the novice, or at least the terminally forgetful. If anything else, the Training Wheels vocabulary should be heavily biased towards the newbie, rather than even a moderately-experienced reader. There is another, more important reason why this newbie bias is the right thing to do. It is much easier to skip over a concept that you already understand in a text, than try to discover the explanation for a concept presented in the text that you don't understand. If a moderately-experienced reader reads a TW vocabulary entry and encounters a passage that they already understand, they can simply skip over it. If the novice reader encounters a passage they don't understand, how do they find where that concept is explained in newbie-language? They probably won't even know what keywords they should search for, in the overall document. It is important to explain every concept in the TW vocabulary as if to a novice. This doesn't mean that we have to put the explanation for rank in every TWV entry, since that is what hyperlinks are for. When the novice encounters the word "rank" in the explanations, that word should be hyperlinked in the text to a full page, explaining the concept of rank in several different ways, with lots of examples. In that way, every TWV entry that needs to explain rank to a newbie who happens to start on that page, can reference that same hyperlinked page on rank. Generally, common and global concepts in a TWV entry should always be hyperlinked to an appropriate explanation page. Concepts unique to a specific primitive should be explained on that primitive's TW vocabulary page. This seems obvious, but it is rare to see this done correctly. Note that I use the words "explanation" and " example" rather that "definition" when talking about the TWV entries. The word "definition" has connotations of formality, conciseness and brevity. that is the exact opposite of what a TWV entry should be. The TWV entry should be redundant, verbose, and explanitory. Both entries should be correct, however. Skip Cave <<<>>> Raul Miller wrote: > On Tue, Jan 26, 2010 at 11:39 AM, Skip Cave <[email protected]> wrote: > >> The training wheels vocabulary should be designed for the total newbie, >> who sees a J expression somewhere, and goes to this TW vocabulary to >> analyze that expression. The only thing that newbie should need to know >> to use the TW vocabulary, is that J primitive symbols can be one or two >> ASCII characters. Hopefully, that should allow the newbie to click on >> the symbol they are interested in, and have its' function explained, >> assuming no prior knowledge about J. >> > > I sort of agree with you, though not completely. > > I think we have other use cases. Yes, we should try and > be useful for people with no knowledge of J. However, we > should also be useful for people who come back after > reading a page or two. > > For example, I think every "ad hoc vocabulary" page should > link to one or more official reference pages. This will help > some people with intermediate knowledge levels and this > can also be useful for people editing a wiki vocabulary page. > > Thanks, > > ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
