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.
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. .
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.
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.
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.
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
