> From: Skip Cave
>
> Ric, Your prototype training wheels vocabulary page and its'
> greater-than entry provide an excellent framework and jump-start, to
> the
> reference-tutorial project. Having an actual prototype layout makes it
> much easier to spot what works, and what doesn't. Thanks for all your
> efforts.
Thanks. Note that Devon is to thank for getting the ball rolling!
> I have a few early comments that struck me upon first viewing. I
> hesitate to make changes in the wiki, as I'm not sure I could do that
> without courting a formatting disaster. In any case, I prefer to get
> some feedback from others before I go mucking up your beautiful layout.
> So I will just state my comments here.
>
> 1) The colors are pretty, but just like the original vocabulary, they
> require considerable previous knowledge of J to be even marginally
> useful. As I have argued previously, this reference-tutorial should be
> heavily biased towards the true first-time novice. Any attempt to
> include cryptic colors, words, or concepts without copious
> explanations,
> will cause more problems than good. This is particularly true for the
> page that may become the primary gateway for novices to approach the
> language.
>
> The colors themselves may not be terribly off-putting, as the newbie
> may
> just ignore them. However, when the newbie looks up the color key and
> finds "verb" and "adverb", they will start wondering if they have
> stumbled into a beginning English class, rather than a programming
> language. The opening page of their explorations might not be the right
> place to lay the whole "J uses English parts-of-speech terminology
> instead of programing terms" paradigm on them.
>
> if we do want to keep the colors, we will need hyperlinks from the key
> words "verb", "adverb", etc.to an explanation that will hopefully calm
> their shock and mitigate their skepticism at this new terminology for
> concepts that they feel they already have more familiar terms for (or
> at
> least so they think). That text could be a challenge to craft. Or, we
> could just use more familiar programming terms such as functions,
> variables, constants, etc. to minimize the initial weirdness barrier,
> and introduce those terms later. Of course, "later" is a difficult
> concept for a random-access tutorial. .
Note that the "Parts of Speech" heading above the words "verb, "adverb" ... is
a hyperlink to an (as yet) non-existent page that I envisage would introduce
the Verbs, Adverbs, Conjunctions etc and relate them to other more common
programming terms.
> I believe that this initial experience will be a critical issue to get
> right for the training-wheels vocabulary. If there is too much
> weirdness
> on the introduction, the newbie won't keep going. The whole point of
> the
> reference-tutorial is to lower the slope of the learning curve for the
> toe-dipping novice who wants to just check out J to see what all the
> fuss is about.The fewer new concepts you have to introduce to gain
> understanding of a particular primitive or concept, the better. It
> could
> be argued that the whole parts-of-speech naming paradigm is one of the
> significant causes of the steep learning curve of J.
I understand your point, but I suppose that I am leaning more to Oleg's POV
that the page should be useful to J learners in general and not only newbies.
IMO the English parts of speech terminology is too good a fit for the concepts
of J to ignore.
> 2) The greater-than description provides two different descriptions for
> the same symbol without any explanation as to what that is all
> about.The
> astute newbie might figure out from the examples what is going on, but
> I
> wouldn't make that the only way to discover why there are two
> definitions for the same symbol. There should be at least some brief
> explanatory text with each description about right-argument-only and
> left-and-right-argument forms, that a novice could grasp easily. The
> terms monadic and dyadic are not universally understood, but they could
> be used with brief explanations and hyperlinks to detailed
> explanations.
There is obviously a balance between the needs of someone brand new to J and
someone who is learning J (has read a couple of these pages before). For
someone brand new to J it might be nice to repeat the basics on every page so
that whichever one they end up on first they have their hand held. However
once the user has been to a couple of pages I imagine that text will become a
nuisance more than anything else. My feeling is that the people who will end up
sticking with J, won't be put off so quickly.
The compromise I chose was to hyperlink the terms "Monadic form", and "Dyadic
form", in the table at the top left to an, as yet, non-existent page called
Vocabulary/Valence that would explain what the terms mean. In addition each
simple explanation will start:
== {Monadic name for primitive} ==
{primitive}y gives ...
== {Dyadic name for primitive} ==
x{primitive}y gives ...
I'm hoping that should be enough, but perhaps you are right and more is
needed...
> It would be best if we could come up with a few words that describe
> monadic and dyadic concepts which could be placed right at the point of
> encounter. That would have the most chance of getting the point across
> to the casual reader. We could also put the words monadic and dyadic at
> the end of the brief description, with hyperlinks to the more detailed
> description. In that way the newbie gets the basic concept in a few
> words, then sees what J-ers call it (monadic or dyadic), and then can
> hyperlink through that word to a more detailed discussion of the whole
> concept if they like.
> .
> .Something like:
> --------------------------------------------------------------------
>
>
> Ceiling - right argument only (monadic)
>
> >.y gives the /ceiling/ of y , that is, the smallest integer greater
> than
> or equal to y
>
> .etc. etc.
>
> -----------------------------------------------------------
>
> The word monadic should be hyperlinked to a detailed description of
> monadic functions.
>
> Remember, this description may be the first thing the newbie sees when
> they go exploring J. That "first-time" theme must be pervasive
> throughout the TW vocabulary. Every description will be a "first-time"
> for someone.
Maybe as well as a name the project needs an agreed upon
"Scope"/"Audience"/"Purpose".
As I've mentioned above, my thinking is that writing every page as if it were
the starting page for a J first-timer, will limit its general usefulness as a
resource.
> Well, that's enough for now. I will await comments....
> .
> .Skip Cave
>
> <<>>
> Sherlock, Ric wrote:
> > (This problem is certainly a disadvantage of this page naming
> schema!)
> >
> > I suspect that your email client (like mine) is trying to be too
> smart and is not including the trailing fullstop in the URL.
> >
> > Try this link:
> >
> > http://www.jsoftware.com/jwiki/Vocabulary/greaterthan%2E
> >
> >
> >
> ----------------------------------------------------------------------
> For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
