Oleg wrote: > Both simplicity of language and clarity of narration may require > constant attention.
Agreed [1]. > I would think, Simple English Wikipedia > http://simple.wikipedia.org/wiki/Main_Page I'm not sure we need to swing the pendulum that far in the other direction, nor assume our audience is as unfamiliar with English as it is with J. I personally picture a J newbie as intelligent but ignorant (of J), and I would pursue my writing under those assumptions. > The name "Wordbook" may be appropriate. > It is a synonym for "dictionary", yet conveys > simplicity, smaller scope, less intimidation. Here is an example: if I were new to J, and someone directed me to "look that up in the wordbook", I might feel condescended to. I would not feel condescended to if I were directed to the "dictionary" or the "vocabulary" (which is more precisely what "wordbook" connotes to me, in contrast to "dictionary"), though I would have a separate set of questions regarding those names. Reflecting on that (the set of questions I would ask), it occurs to me that the word we're seeking is right under our nose: The J Manual. "Look that up in the manual" seems just about right. Unfortunately for me, I take great interest in J-as-a-language, and value how the current DoJ presents it as such, but I don't feel the "language analogy" presentation is appropriate to a "manual" (as opposed to a dictionary). So now we're at the fuzzy border between form and content [2], and we must consider how to cross it. We actually get a lot of complaints regarding the presentation of J as a (human) language; is this the time to abandon (or tune down, or twist) that analogy? The question again hinges on our intended audience. Pragmatically speaking, most newcomers to our language will come from other (though perhaps exotic) programming languages, not as the tabula rasa the current DoJ targets. So shall we target that pragmatic audience, and write our manual as other manuals are written [3]? Or does that lose the value of a differentiated language in the first place? Would abandoning the human-language analogy be to lose one of our tools of thought? I don't know (and I would be personally sorry to lose the analogy), but I thought I'd raise the question. Especially in light of Don Guinn's comments: > A section in help called "HowTo". This would be a > list of words and phrases used in other languages like FORTRAN, C, > etc. I agree this is a worthwhile pursuit, but it is different from a "dictionary" (in the monolingual sense), because there will be no one-to-one correspondence between J and these other languages. We could call it "HowTo", or use another term such as "the J-FORTRAN dictionary" or perhaps just beef up our current (and aptly named) "phrase book". The NYCJUG has such a project under consideration (taking VB's index and reproducing it for the J market). For concepts that DO map one-to-one from English or other computer languages onto J primitives, I like this idea: > { Index, Subscript Similar to subscripting in other programming languages > # Copy Pick items based on a mask > /. Key Group items based on a key > {. Take Take beginning items > }. Drop Drop beginning items and would lobby to include it as another "tab" along the lines I sketched at the bottom of [4]. -Dan [1] But again, I would've been happy with an internal name for the project, a name for "us", not a name for "them". And so simplicity would be less of an obstacle. [2] "Content is just fancy form." -- Douglas Hofstadter [3] And how are other manuals written. In particular, I find Dyalog's manual pretty accessible, but then I came to it knowing J, so I was already "booted up", as it were. Does K manual receive much criticism or praise? What about other "weird languages"? [4] http://www.jsoftware.com/pipermail/programming/2010-January/017993.html ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
