On Mon, Feb 8, 2010 at 12:27 PM, Raul Miller <rauldmil...@gmail.com> wrote: > On Mon, Feb 8, 2010 at 4:55 AM, Ian Clark <earthspo...@googlemail.com>wrote: > >> ...I mean, why not put ">" ">." ">:" all on the same page too... >> aren't they supposed to be the same symbol "inflected"? > > That leads to the problem of the novice finding the relevant > material after loading the page.
That problem exists already, with verbs. The suggestion wasn't to be taken at face value, but only to hilite this fact. > That said, a "see also" at the top of the page, for alternate > spellings (somewhat along the lines of Prev/Next links) > might be appropriate for novices. Yes! Loads of those. One in particular I'd like to see is reference to relevant words in the z locale. Users should be introduced to those right up-front. Maybe more important for the bangcolons than, say, plus or greaterthandot. > how much introductory material should be repeated on > some or most pages? (for example, treatment of > spelling, grammar and rank) Introductory material ought not to be dumped (raw) into reference material. Judicious pointers should be used. And they should appear, repeated, on every page. Otherwise, which pages? A novice may never bother to look at the page for plus (say), only at those pages which are instructive in something meaty, like semicoloncolon > how much exposition should be by example (J > sentences with responses) and how much should > be using english sentences? Zat Is Ze Question. Answer: as appropriate. But how to tell? The only way I know that works is by systematic experiment. Expensive and tedious. But anything else is guesswork, whatever else it masquerades as. > should some pages have pre-requisites, where the > reader is advised to study other pages first? No. Nothing more annoying. If a reader is told: go off and read such-and-such a page [ chapter [ book]] before you can ever hope to make sense of this page, might s/he not ask: why can't you tell me what I want to know, right here? Leave me to judge whether I need to read some explanatory notes. Task-oriented help material is written to be evaluated on how well it supports (the) tasks. ...A pre-agreed list of tasks (sorry I haven't done those yet). Hypertext does away with the need for the traditional didactic approach. Traditional didactic stuff is written to look good [ right [ familiar]] to those who already know what it's all about. That's the only rating it gets for fitness-for-purpose. If it perplexes the novice, then JTB -- the novice is only a novice, i.e. ignorant. ...We don't want yet more didactic stuff. We've got a load already. LJ. JforC... It's good enough, if you've got time to read it. > should some pages have introductory/advanced > structures where we first introduce the reader to > some essential cases and then come back and > treat the operation with more rigor? I gagged at the word "structures". What wrong with a bunch of examples of increasing depth? If prerequisites are needed (e.g. a knowledge of advanced statistics??) what's wrong with simply-phrased links? You can word them like so: "...this assumes you know [statistics]" And that's why I'm not a fan of special icons, e.g. intended to signify "essential", "recommended", "nice to know", etc, etc. You're inventing your own heiroglyphic language and demanding the reader learn it as a rite-of-passage to your mysteries. Glyphs do have their place, i.e there are valid tasks they support. But far more restricted that their popularity suggests. > In all cases I think we should favor "ease of digestion" > over "ease of preparation". The dictionary is not outrageously > big and while automated page building can be tempting > if need be we can rewrite pages from scratch using copy+pasted > text rather than trying to extract content from over > complicated wiki markup (I hope). You're right to subordinate "ease of preparation" to what's needed to do the trick. But can you reliably predict "ease of digestion"? -- I can't. But simplicity is a start. KISS, don't they say? The purpose of "automated page building" -- which is not quite what I proposed, but I'll go along with your choice of term -- is to allow subsequent inclusion of additional task support on all relevant pages (see-also's, warnings, explanatory notes, whats-thisses, refs to the z-locale...) as we identify the need for it. But if I'm to manage a consistent set of pages, then I reserve the right to enforce consistency by some automated method or other. At worse (not knowing enough about moinmoin) that will mean an occasional batch-regeneration exercise. But I've done it so many times I think I know how to do it now when it will actually help and avoid it when it won't. Horses for courses. I don't pick my screwdriver and then go looking for the screw. > For now let's just > try to keep the markup simple enough that it does > not stop us? Oh definitely. Leading requirement. Main thing is to march to the same tune, however simple. Ian ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
