On Thu, Feb 4, 2010 at 4:07 AM, Sherlock, Ric <r.g.sherl...@massey.ac.nz> wrote:
> 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.
I agree. We shouldn't get hung up on this.
Succinct doesn't have to mean "opaque". Verbose text can be just as
opaque, thanks to the verbiage you have to trawl through. And does
anyone of us really know how to write a good "starting page for a J
first-timer"?
{Puts human factors hat on...}
When I speak to intelligent people who know nothing about human
factors (...does anyone know nothing about human factors I mean we're
all human haha...) I find that they assume "novice-friendly"=verbose.
But IME what non-plusses a novice is quite literally that: "non plus
ultra" -- no obvious way to proceed. Viz. the ladder you are offering
has missing rungs.
But once you know there's rungs missing, they're easily supplied.
Provided you've been consistent in developing your material. If your
material is succinct (as the Dic and Voc certainly are) it's a lot
easier to check [/enforce [/control]] consistency.
Then you can fix the ladder.
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?]"
It goes without saying that these links are best provided on the
template. They'll be on every page, but they'll only be clicked once.
The big risk is they won't be clicked at all -- and the novice turns
round and asks the very question they're there to answer. (Seen it
happen.)
Correct use of colour.
(Robertson, P. J., A guide to using color on alphanumeric displays.
IBM United Kingdom Laboratories, Winchester : 1979)
Colour is supremely good for two things -- and two only: (a) drawing
the eye, (b) implicitly asserting a relationship between separated
objects. It's a survival mechanism: it lets you recognise a tiger even
if there's a big tree trunk splitting its retinal image in two. But
use colour sparingly, i.e. to support only one task at a time.
Otherwise it soon becomes visual noise.
If using colour for task support, avoid it for decoration. Even very
intelligent people don't know the difference between task support and
decoration when it comes to colour. Don't believe me? Then ask what
task is supported by exhaustively colouring every verb, conjunction,
etc (...suggested but not used yet).
Ian
On Thu, Feb 4, 2010 at 4:07 AM, Sherlock, Ric <r.g.sherl...@massey.ac.nz> wrote:
>> 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
>
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
