Talk:Array Manipulation
Please comment on the need or value of such a collection, the desirable degree of detail, and general style of presentation. Thanks. --Art Anger
This is much-needed Art. Thank you.
Back-links to this cookbook could usefully be inserted in several places in NuVoc, as well as where Art suggests in the forum.
There are standard formats Henry and I have been using of referring in a NuVoc primitive-page to another page. Examples…
I have a set of templates for this format and would be pleased to insert links where appropriate. Not at every occurrence of a term or primitive, perhaps (which would be tiring on the eye), but where we judge they are beneficial.
I guess this is best done when this collection is substantially complete. Ian Clark (talk) 08:22, 4 May 2022 (UTC)
Thank you Art
The only suggestion I have is to use the name of the primitive in the description as well as the title of the section. I can see what you mean to do because I know the names of the primitives, but a newcomer might not catch on that "Returns an ascending (or descending) sequence of integers" refers to the work "Integers" in the previous line as an example. Cheers, Bob Therriault (talk) 21:30, 4 May 2022 (UTC)
I think it would be useful to be able to collapse the examples, brief as they are, and offer a Show button. My attempt, however, failed--the <pre>-bracketed code popped up ahead of the collapsible section.
The page is substantially complete as I have envisioned it.
If I don't receive complaints or alternatives to my occasional reworded descriptions, I plan eventually to make similar revisions to those NuVoc pages.
Remaining questions: --Can any reasonable formatting changes make the page more attractive, or compatible with others? --Can any other aids be easily included?
If you plan to retrofit the wording used here into NuVoc, please note that NuVoc was written to support a different task from that of this wiki article (let's call it AM, for Array Manipulation).
By task-support I mean what IBM did in the 80's and 90's when it completely altered its approach to documentation in the light of its own vast ergonomics/HF research program. Plus its experience of writing for a whole new audience with the launch of the IBM PC. I don't want to expand on the theory here, except to hint at the task(s) supported by NuVoc vs AM vs Dic (the original "J Dictionary"). Both AM and NuVoc fill glaring gaps left by Dic. But they are different gaps.
- NuVoc: answer: what in simple language does [this] primitive do?
- AM: answer: how in J is one meant to manipulate arrays / in [this] given way?
- Dic: offer a standard definition of the J language.
For NuVoc, Henry and I resorted to "babytalk": how you'd address a 4-year-old. One whose first language may not be English. Not to insult the reader's intelligence, but to recognize that at the point-of-use the reader was preoccupied with solving their own puzzle -- one which absorbed their language-comprehension skills. For AM the reader's task-in-hand is different: it is precisely the task AM is meant to support.
IMO the current wording of AM is entirely appropriate. But for NuVoc it may not be. This is not to say the wording of NuVoc is ideal. It isn't. I can give counter-examples from both Append (,) and Stitch (,.).
Neither Henry or I have offered guidelines for how to write a new NuVoc page. This is an omission (it's been on my to-do list for 2 years now). But the critical wording is everything above More Information. From that section onwards the wording doesn't matter, since anyone with the leisure to read that far down has time to digest the prose and look up terms they don't understand. Ian Clark (talk) 14:57, 11 May 2022 (UTC)
Ian-- My primary purposes in rewording were for logical accuracy and unequivocal proper English. I don't think that I have strayed much from the descriptions I copied from NuVoc pages.
I found that I had included Copy in two sections, each emphasizing a different use, and decided to leave them so.
I have modified or expanded a few Examples for a clearer or fuller illustration of a concept. --Art Anger (talk)