Guidelines for editing the Accessible Vocabulary (NuVoc)

What does NuVoc do?

NuVoc delivers rapid answers to the following user questions...

1. What does this given J primitive do?

2. How am I meant to use it?

3. What's it commonly used for?

4. Where should I go for more information about it?

NuVoc achieves these goals by having minimalist content, predictable layout, pre-generated links and simple language.

If special J terminology is used, like atom or list (unqualified), it is explained, or a link given to an explanation.

Who is NuVoc aimed at?

1. Someone not yet familiar with J terminology.
They will not appreciate an explanation couched in terms they don't understand. Nor will they appreciate having a term explained to them (like rank) which is then going to be used as the vehicle for an explanation, if this is unnecessary. Teaching the reader to talk "J" is a different task from the one in-hand.

2. Someone trying to read a sample of published code.
They will not welcome being hit by a dense block of text, since their mind is filled up with the details of the code and how it supports the task in-hand.

3. Someone asking: what does this primitive do in that position in that phrase?
They will appreciate a simple answer to what they may think is a simple question.

4. Someone trying to use a primitive they have chosen via the NuVoc portal because it looks like what they want, but with little success.
They will appreciate examples couched in a form they can grasp at first sight and adapt to their own purposes, and which will work first time.

Stylistic guidelines

The "naive" aspect of NuVoc may conceal the fact it's been written to strict rules:

Use "plain English": short sentences, no passive voice, avoid negatives, especially double-negatives, no circumlocutions.

Avoid words like atom which have a precise meaning which only J-ers can be expected to fully understand. If you can't avoid using such a word, like list, then qualify it to make it clear you intend its plain-English meaning, not its J meaning, e.g. list of letters.

Keep the reading age low. Think of Groucho Marx's four-year-old. Even readers with a higher reading age will benefit from this, if their attention is directed elsewhere, viz towards the problem they are currently grappling with.

Avoid complex or "clever-clever" examples. NuVoc offers no scope to show off. A mundane example may be exactly what's needed, crass though it may look to the wise J-er.

Avoid language projecting an air of authority (e.g. "officialese"). The page should remind the reader of a Mr. Men book, not a public notice.

Break code-samples up and invent evocative names for sub-phrases if this helps clarity. But try to use the operand names in the page title, viz. x y u v m n, where appropriate.

If nouns have been assigned for a given example, it's okay to re-use them further down the page (but not dropping through into the dyadic section).

How NuVoc differs from a textbook

NuVoc is not a substitute for a textbook.

If the reader's prime task is to learn J, then they need one of the J textbooks to be found on this wiki.

NuVoc is badly structured for a how-to book. A reader with a coding problem needs to move from his or her (non-J) understanding of what's needed to the actual J primitives which will serve the purpose. Studying the NuVoc portal may occasionally solve this problem. Thus Matrix Inverse (%.) and Square Root (%:) immediately suggest their uses. But that is not true of Rank (") or Under (&.:). The task-support NuVoc offers here rests purely on the names it gives to the primitives themselves.

A textbook can develop a treatment. It can introduce special J terms as it goes along. It can expect earlier chapters to have been read and understood.

NuVoc can do none of these things. It must be written as if every page is the first such one the reader has ever read. It cannot assume the reader has read even the briefest preliminary page, although the NuVoc portal does in fact point to several ancillary pages explaining important J concepts. It can try sending the reader back to take a mini-course of study before continuing, but the reader is unlikely to comply.

Format of a NuVoc page

NuVoc is not the only source of information. It shouldn't pretend it is. If the simple structure outlined below is genuinely not enough to convey a practical "first-aid" grasp of the primitive in question, then give a link (in-line) to the J Dictionary for a deeper explanation, or to an essay elsewhere in jwiki. Example: Fit/Customize (!.)

A great block of text demanding that it should be swallowed whole and entire, or not at all, presents a forbidding aspect to the newcomer, who is coming to NuVoc for instant information. (There are plenty of sources of voluminous information, all of which need concentrated study and thus are not suitable for on-line help.)

All titles have been pre-generated in a consistent fashion. Please don't alter them. The same goes for the small-font links just below the title.

The narrative starts with a sentence in plain English saying what the primitive does. Example (taken from (>): "Opens a boxed item or array of boxed items."

The opening sentence should usually start with the verb in the third person, present tense, e.g. "Opens a boxed item..." rather than ">y opens a boxed item..." (because >y is redundant here). This isn't possible with some adverbs, which need a different description for differing calling syntax.

There follows a simple example merely intended to express in code form what's just been said.

Next comes a section of (numbered) Common Uses. Often this section is redundant. But sometimes it's not clear from the foregoing just how the primitive is used in practice.

Next comes a Related Primitives section, which contains links to "sister" primitives.

Thus Increment (>:) shows a link to Decrement (<:).

Next come one or more optional sections:
- - More Information -- goes deeper into how the primitive works
  - Details -- additional facts for advanced users to remember
  - Oddities -- strange or unexpected behavior of the J engine
  - Use These Combinations -- the relevant extract from the tables shown in: Vocabulary/SpecialCombinations.

Monadic and dyadic uses of a given primitive share the same page, whose name simply describes the letters in the primitive, e.g. "gtdot", with no reference to their meaning

Otherwise monads and dyads behave like separate pages. Each can be accessed by an "anchor" appended to the URL, viz. #monadic or #dyadic. Each may make reference to the other, but don't assume a reader accessing the dyad is necessarily going to read the monad section as well.

Vocabulary/GuidelinesForEditingNuVoc