> I don't know of any useful task the novice wants to perform which > needs both the monadic and dyadic forms of a given primitive to be on > the same page. So let's have them on separate pages...
Oops... yes I do... The sub-task of answering the question: inside a given expression, is this primitive a verb, and if so is it being called monadically or dyadically? But I think it's a feeble way to support the task: to offer material on what is usually two distinct functions on a single page and let the reader decide which is relevant. It was certainly the hardest (reference lookup) task for me as a novice: deciding whether the monadic or the dyadic half of the page was the one which held my answer. Since most Voc pages I consulted in anger were quite opaque to me (I had my mind on my own problem and I wanted rapid help with using ther primitive correctly in my own context) it didn't much matter, and I fell back on trial-and-error. In other words the page failed me utterly. That's why I'm appealing for code examples to be (a) ultra simple, (b) ultra flexible. With humble respect, judging a "good" code example isn't something aesthetic, it's measuring what works to support the novice's task. Experienced J-ers are honestly the last people qualified to judge. Unless that is, they have access to genuine novices, whom they can observe in action. I can't think how to design effective task support for: "Monadic or Dyadic?" Do I understand there will be a J engine available to execute code for the reader? That would make all the difference. Ian On Sun, Feb 7, 2010 at 8:50 AM, Ian Clark <earthspo...@googlemail.com> wrote: > I think we're likely to get into a situation where we've developed a > complex template on the basis of a very few examples which prove to > have been too simple ones to choose, or the wrong choices. We then get > a raft of better idea, or experimental verification (or the opposite), > and it becomes clear we ought to retrofit a new template regenerating > all the pages, which means unpicking the content from the formatting. > > Let me make an offer, in an area in which I can claim some track record: > > That is, to maintain on behalf of the Team a collection of "content", > in a way which defers decisions on the best page format. Or > typographic tricks, eg to hilite, say, useful / required terms, a-la > the For-Dummies books. > > On http://www.jsoftware.com/jwiki/Vocabulary/ I count some 120 J > primitives, most of which have monadic and dyadic forms. That's at > most 240 primitives, if monadic and dyadic forms are given their own > wiki pages. Plus another 50-100 pages if each comma-bang (=Foreign) is > given its own page. This is not a huge collection to maintain, > especially as most will be quite short. Once decided upon, their > number will be fixed. Or at least new pages will only be needed when a > new J primitive is introduced (most likely another comma-bang). > > I'll have to experiment a bit, but I know roughly what I'm going to > do, and I'm going to use J to do it. Once I have that in hand I'll be > happy to accept as my input the Raw Text of a collection of MoinMoin > pages. > > From all that I've read so far, we could go ahead with Ric's template > as illustrated by: > http://www.jsoftware.com/jwiki/Vocabulary/greaterthan./ > and defer the fancier typographic decisions until we've got a complete > set of content pages. > > This will allow us cooperative working with tools we understand well > enough (J wiki pages). It will yield a fixed set of pages consisting > largely of narrative + examples, easy pages to pour into some future > template. Via some batch generation process, which I will write and > maintain. > > As we compose these content-rich pages, the requirements for the > template will gradually emerge. But no sweat if we don't get it right > first time. So I suggest we just go ahead. Now! > > In the next week I'm going to come up with a list of tasks -- common > novice tasks -- to be supported by the NuVoc. What I mean by "task" is > what a HF engineer means: a step the user (typically a J novice) needs > to perform to achieve her goals (of understanding J better). > > NOTE: Tasks are not functions: functions are computer capabilities > that "support" tasks. It is to be hoped the tasks are useful ones, and > all the commoner ones are comprehensively (and comprehensibly) > supported. But so seldom is the relationship 1-to-1 between task and > function. > > Examples of tasks: > 1. Finding out what ">." (say) stands for > 2. Finding out if (say) ">." has a sister-primitive and what it is, > viz in this case "<." > 3. Finding the J code word for the primitive known as "Ceiling", ditto > "Floor", "Max", "Min", ...etc. > 4. Finding what J primitive(s) correspond(s) to the Visual Basic function: > Int() > 5. Finding what part of speech is ">." > 6. Finding out if there's a handy verb in the z-locale which uses or > delivers: "1!:2" > ...and so on and so on. > > Just one change I'd like to propose to Ric's design, but it will > simplify each page and make a successful all-inclusive template a lot > easier to invent. That is: to give monadic and dyadic cases of *all* > primitives their own separate pages. > > Now what I'm going to say next is sheer heresy... > > I don't know of any useful task the novice wants to perform which > needs both the monadic and dyadic forms of a given primitive to be on > the same page. So let's have them on separate pages. At least to start > with. They can always be stuck together later if I'm wrong: deciding > whether this-way-up or that-way-across can be deferred. > > If we can all agree to this, then it follows that a good title for the > page explaining dyadic ">." is "x >. y" and not just ">." > > It follows from this that all the examples can be couched in terms of > x and y (u, v,...). This will work both inside and outside an explicit > definition. Furthermore (and I'm getting controversial now...) *all* > examples will benefit from being couched like this: > value=. 300 > x=. 3 > y=. i. 6 > value x}y > > and not like this: > > (300) 3 } i. 6 > > or: > > 300 (3) } i. 6 > > which demands the novice to perform too many mental sub-tasks at once, > only one of which matters. > > Once the user has absorbed the "anatomised schema", i.e. the first > example: "value x}y", then confounded forms like "(300) 3 } i. 6" are > easy to infer. And what's lost if they aren't? Moreover the novice > might even see for herself without having it explained in gory detail > just why "300 3 } i. 6" isn't going to work, nor any of the 99 other > ways the novice might try of splitting "300 3". > > NOTE(1): Space is not important on a Wiki page (though it may well be > important on the printed page, in terms of cost and layout). > > NOTE(2): The above example is too simple for the alternatives to > matter much. But think of what's entailed with dyadic ";:" > > NOTE(3): The anatomised schema lends itself to having recurring stock > nouns, such as "i. 2 3" or: > > az=: 26 {. 97 }. a. > a23=: 2 3 $ az > > which the novice will soon come to recognise (and may even write into > her profile). This will aid experiments, there being one less thing to > think about. It saves distracting the novice from the task in hand > into a mental analysis of the sample value currently being used. > > The existing Voc is a bad offender here. Picking an example at random > (from Power)... > > (] ; +/\ ; +/\^:2 ; +/\^:0 1 2 3 _1 _2 _3 _4) 1 2 3 4 5 > > ...easy to appreciate if you know J already. Somewhat less easy if you don't. > > I'm prepared to be steamrollered over my recommendation for couching > examples. But can we now agree a working "Ric" template so we can all > get started before our motivation goes off the boil? > > I'll just repeat what I offered {...deep breath}: to get some 240 > content-rich wiki pages into a final unified, cross-referenced form. > Provided their existing format is simple. > > Ian > > > > On Fri, Feb 5, 2010 at 8:13 AM, Skip Cave <s...@caveconsulting.com> wrote: >> PackRat, >> >> I think the red exclamation point is a good idea. I have created two >> graphics, one red exclamation point graphic, and one blue question mark >> graphic. Here are links to both graphics: >> http://teledon.info/Jvoc/Exclaim1.png >> http://teledon.info/Jvoc/Quest1.png >> >> The exclamation mark graphic should be be used to indicate required >> reading. If the reader doesn't understand the hyperlinked word or >> concept next to the red exclamation point graphic, they should follow >> the associated hyperlink (on both the word and the graphic). The >> hyperlinked text. will explain a concept that is critical to understand >> before proceeding further in the current text. >> >> The blue question mark graphic should be used to indicate words or >> concepts that provide useful information, but that are not immediately >> required to understand the current text. However, that information may >> become required at some other place in the text (at which point it will >> be marked with a red exclamation point). . >> >> An interesting example of the use of these graphics, is the word >> "Monadic" On the opening Vocabulary page the word "monadic" should have >> a blue question mark next to the word, as at that point (on the front >> page) it is not critical to understand what "monadic" means. However, on >> the Ceiling page, the word "monadic" needs a red exclamation point >> beside it, since on that page, it is critical to understand what monadic >> means in order to help make clear the reason why there are two different >> explanations under the Ceiling description. >> .. >> .Skip Cave >> . >> PackRat wrote: >>> Skip Cave wrote: >>> >>>> 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. >>>> >>> >>> Perhaps a red exclamation point might be better than a question mark to >>> emphasize the critical nature of some concept. I agree, too, that >>> these need to be graphics or else a significant change in font size >>> (and perhaps font, too) and not just using the same font and changing >>> only the color of the character. >>> >>> By the way, the "... for dummies" series and similar series have >>> various kinds of visual markers for the beginner in terms of important >>> concepts or "for more info..." and the like. Perhaps some of these >>> could be developed into online equivalents... >>> >>> Harvey >>> >>> ---------------------------------------------------------------------- >>> 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
