Raul Miller wrote: > how much introductory material should be repeated on > some or most pages? (for example, treatment of > spelling, grammar and rank) > Since every description/tutorial page in the "verbose vocabulary" could be the first page that a novice encounters, there needs to be a way to give a novice access to the key concepts they need to understand, on every vocabulary page. Ideally, some of this key-concept-access scheme would be built-into the template for all the vocabulary pages, though some references would be better placed in the description text for each primitive.. The trick is how to do that without cluttering up the page too much with alternate-topic text and verbose hyperlinks. I think that the "!" and "?" graphics in the descriptions deliniating "required reading" and "nice to know" topics respectively, are the most promising approach. A simple graphic shouldn't annoy the more advanced reader too much, yet it provides the novice instant access to the concepts they have to understand, to continue their learning process. I can't emphasize too much how important that "instant help at the point of need" is. > how much exposition should be by example (J > sentences with responses) and how much should > be using english sentences? > J sentences should be used whenever the novice should be at the point where they know enough J to readily understand the code. If there are some radical new concepts to be introduced, it would probably be best to explain the process in English perhaps with hyperlinks to a video, before reinforcing the concepts with J code. We have to keep in mind that this document is targeted to the novice, not the intermediate or expert user. It is much easier to write for the expert user, since the writer can assume that the reader already knows all of the required concepts to introduce a new, advanced concept. The novice reader has no such background, so the writer must make sure that even simple concepts be explained (or hyperlinked to an explanation), no matter how basic, before going to the next step. Also, cryptic hints or color codes embedded in the descriptions to aid the advanced user should be avoided, to avoid confusing the novice. > should some pages have pre-requisites, where the > reader is advised to study other pages first? > That is one of the issues I've been struggling with. Should there be one or more "read me first" pages that the true novice should be encouraged to read before tackling the verbose vocabulary? Or, should the new concepts be introduced in the text descriptions at the point where the knowledge is needed? I tend to think that the "read me first" approach is not as effective, and kind of a cop-out, that avoids having to solve the effective but more-difficult-to-implement "elucidate at the point of need" approach. > 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? > That is a tried-and-true educational approach, and is probably the best way to bring a novice up to speed rapidly. > 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). For now let's just > try to keep the markup simple enough that it does > not stop us? > Excellent advice!
Skip Cave ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
