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
