Vocabulary/AboutNuVoc
About the Accessible Dictionary: how and why
This announces The Accessible Dictionary Version Two (June, 2014), a.k.a. NuVoc.
Accessed externally via the URL: http://www.jsoftware.com/jwiki/NuVoc, it follows the layout of Voc, the iconic one-page portal to J's primitives which forms the best-known part of Hui & Iverson's J Dictionary. Consequently The Accessible Dictionary in its entirety in known informally as NuVoc.
The goal of NuVoc is to be the "one-stop shop" for all J users, beginner or advanced, seeking explanations of the language and its correct use.
NuVoc calls itself The Accessible Dictionary because
- It is written in a style to make it accessible to novices
- It has many supporting essays, plus an extensive Vocabulary/Glossary
- It is extensively hyperlinked to allow easy navigation around its material
- It collects J documentation in one place for the benefit of even J experts.
Voc is a praiseworthy piece of work. It is concise, precise and consistent, employing a terminology (nouns, verbs, lists, etc) that is among the tersest and least cluttered to be found in any discipline. But J newcomers tend to find it rather dry. Also it uses familiar IT terms like "value", "array" and "table" in a precise but idiosyncratic way.
NuVoc currently comprises:
- A page for each J primitive (sometimes more than one), giving a full description of its use in both monad and dyad valences
- The Ancillary Pages, a set of articles describing facets of J and its use. These are accessed from the primitive-pages for deeper explanations of selected topics
- A comprehensive glossary of all hyperlinked terms in the primitive-pages
- A precise description and analysis of verb rank as it applies to each J primitive, whether verb or modifier
- An exhaustive account of all special combinations of primitives which J singles out for extra-fast implementation
- A description of the error messages and what it means when you encounter each one
- A mini-glossary of 15 or so absolutely essential terms to furnish complete newcomers with a clear, unambiguous explanations of these terms to enable them to approach NuVoc profitably.
NuVoc Version One was completed and announced by Ian Clark on January 20, 2014. It then had a strictly limited objective: to supplement the iconic J Dictionary with an accessible portal aimed at complete beginners. At the time it was not deemed possible, or even desirable, to make it anything more than a superficial introduction to J's primitives, and at the same time achieve a low "reading age", e.g as might be determined by the WikiPedia:Lexile metric.
Why aim for a low reading age? Is NuVoc an exercise in outreach to dyslexics and others with learning difficulties? Alas, praiseworthy though that would be, it has not been a goal of the NuVoc project.
A low reading age is important for reference works for two reasons:
- to minimize the cognitive load on someone having a mature reading age, but focussed on the task of solving a programming problem, not on reading for pleasure
- to benefit J users whose mother tongue is not English, by not wasting their time on researching aspects of literary English which turn out to contribute nothing to the task in-hand.
The impetus to make NuVoc a complete description of J's primitives, terminology and error messages came from Henry Rich, who drafted the wealth of technical detail to achieve this. Henry came to the project with a weighty advantage: besides having written the standard reference work J For C Programmers he actually teaches J to classes of young people.
The challenge was
- to explore and convey, in an optimal way, precise, detailed and often little-known aspects of J
- to structure every page to abolish the need to read the entire page in search of answers to frequently asked questions
- to preserve a low reading age, at least in those stock sections of primary concern to J beginners, viz. the opening and "Common Uses" sections.
These are conflicting goals, impossible to satisfy totally. But we feel a workable compromise has been achieved.
It might be necessary to adjust this compromise in the light of feedback, especially from J beginners, whose pressing need for clear, unambiguous and correct information risks being squeezed out by the preferences of long-time users.
This is likely to arise, and rightly so, if J were to recruit fewer and fewer new users, becoming the preserve of an ageing community of devotees. It would be a pity however if this were to happen not because J has become obsolete and irrelevant to today's IT world (it hasn't) but due in large part to the difficulty of its documentation.
Thanks are due to Ric Sherlock, who designed the NuVoc portal and drafted a layout for the primitives-pages, to others who contributed pages and pioneered presentational ideas, notably Devon McCormick, David Lambert, Bob Therriault and Dan Bron, plus many others who commented on material and offered encouragement. But most of all to Henry Rich, whose monumental and meticulous labours over the last half-year have been truly Herculean! But, as I'm sure all will agree, by no means Sisyphean!
(Apologies to any significant contributors whose names have been omitted.)
-- Ian Clark <<DateTime(2014-06-25T12:57:08Z)>>
Discussion / Report A Bug
Please make comments and bug warnings on the Discussion page (see tabs at top of this page).
Sign each comment with ~~~~ in the usual way.