Ric Sherlock said: Maybe as well as a name the project needs an agreed upon "Scope"/"Audience"/"Purpose".
Skip Says: Yes, absolutely. IMO, the existing J vocabulary and dictionary are an excellent references for the intermediate and expert J user. "J for C Programmers" "and "Learning J" are excellent linear tutorials for the beginner who is willing to spend days or weeks acquiring a general skill with J. What is missing is a reference for the novice who isn't ready to commit such significant time to learn J, but wants to understand some J code that they encountered on Rosetta Stone or other web resource. This audience will want to look up a specific symbol, and want it explained in terms that do not rely on prior knowledge of J or any of J's somewhat obscure terminology. That should be the primary target audience for the J reference-tutorial. I expect that this toe-dipping novice audience will be the largest audience in terms of numbers of unique visitors to the J software site. The J Reference Tutorial should be a conspicuous link on the J Software front page, with a "Newbies start here" note. A secondary target audience would be intermediate J users who struggle with the brevity and encoding conventions of the J Vocabulary, and perhaps need more examples to foster understanding or reminding. So the "Target Audience" for the J Reference-Tutorial should be a complete novice. A secondary audience would be intermediate users who need a refresher on a particular primitive or concept, but there shouldn't be too many concessions in the JRT for this secondary audience. The focus should be on the novice. My rationale follows: I don't particularly want to clutter up a nice tutorial section with repetitive explanations of terms for the novice. On the other hand, as I have stated in an earlier post: 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 likely won't even know what keywords they should search for. Even if they search for a keyword, they may not find where it is defined in a way that they can understand. This is the primary argument for hyper-text linking of words and concepts in a tutorial that will likely not be familiar to the novice reader. The words monadic and dyadic are typical examples of that issue. I can remember when I encountered them for the first time in APL. I had no clue what they meant, and there was no reference dictionary handy to help out. It took me nearly an hour to figure out just what that was all about. I think we all agree on this point, as Ric has clearly hyperlinked the unusual words in the opening page and in the "Ceiling" description. However, Ian brings up a critical point: Ian Said: It's not clear to a novice you'll go anywhere useful if you click a link saying "Monadic", of all things! Find a novice and ask her: what do you think you'd see if you clicked that word? Here's more of Ian's post: Example. The scary words Monadic and Dyadic being the first things to hit you on a page. Remedy: try offering additional links: Monadic [...What's this?] ... Dyadic [...What's this?] ... -rather than hyperlinking just the words Monadic and Dyadic. It's not clear to a novice you'll go anywhere useful if you click a link saying Monadic, of all things! Find a novice and ask her: what do you think you'd see if you clicked that word? Many official websites for the general public use this trick: it works. Another example. The forbidding blue box at the top right. Actually it whispers "for official use only" -- so the novice will filter it out, simply won't see it. Find a novice and ask her. Not: did you see that blue box? (answer: yes of course) but: what's the Part of Speech of "Ceiling"? Remedy: try sticking a link below it: "[...What's this blue box all about?]" -------- Skip Continues: I believe that Ian has an even better idea. Just hyperlinking the word "monadic" probably isn't enough for a newbie. They may not even realize that that word is critical to understand, before going on. After all, the Wikipedia hyperlinks all kinds of words in their text that don't necessarily add anything to the understanding of the topic at hand. The JRT should put simple "What's This?" or "What's this blue box for?" links wherever there is a concept or feature that an newbie should understand, before proceeding further These link notes can be put in a smaller font, or made into a question-mark graphic, to minimize the clutter effect on the page, but they should be there. . A note on the main page should explain to the novice that terms, concepts and features on the following pages that are important to understand, will be marked with a "What's This" link or the question-mark graphic. I had another idea - We could even have a couple of different levels of "what's this" links. Perhaps a "you need to know this" link in bold red font for critical concepts, and a "what's this" link in blue font for the nice-to-know stuff. Or if we really want to keep the text clutter to a minimum, a red question-mark graphic for "need to know" stuff, and a blue question-mark graphic for "nice to know" stuff. The opening page should make it clear that certain concepts are critical to grasp before proceeding further, and then it should explain what the notational help links will look like in the following tutorials, so they know what to expect. This is even more important IMHO, than the verb, adverb stuff that should be on the front page. If we use the help links, we will need to have a very prominent explanation of these help hyperlink symbols on the front JRT page, so the newbie won't miss their critical importance in the subsequent descriptions. . .I think that Ian's idea is the perfect trade-off between verbosity and conciseness. The experienced user can easily ignore the "what's this", "you need to know this", and question-mark graphic links, yet the newbie will be pointed to the things they need to know without cluttering up the tutorial pages too much with repetitive definitions, Thanks Ian, for a great idea!. Skip Cave ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
