In his post, Harvey gives examples where he shows where the keyword
tagging of information is critical to the learning experience. As I have
mentioned in earlier posts, beginners and casual users have a very
difficult time finding how to build the functions that they want in J.
This is primarily because the names that the neophyte might commonly
enter into a search engine to find a specific function or example, is
simply not in J's documentation. As Harvey explains in his post: "the
terms currently used may be quite exact, but many of them are not the
first word that may come to mind for the concept involved; the index of
words needs to include additional alternative English words for some of
the terms chosen as well as inverted forms (that is, both "natural
logarithm" and "logarithm, natural")"
I know from direct experience, nearly 2/3rds of the time, the
functionality I seek in the documentation can't be found because of
missing terminology. The functions I need are almost always there
somewhere, I just can't find them. This isn't an indexing problem. The
J Ndx and the Google domain search does a fine job of indexing. This is
a semantics problem. The words used by the searcher aren't the words
used by the author.
If the user finally does find what they are looking for (often by
posting a request to the forum), it should be standard procedure for the
user, or the person who answered the users question, or the author, to
add the keywords that was used to ask about the function, to the
documentation for that function. In this case, Harvey talks about the
PDF version of the Dictionary in his post, so this isn't a wiki issue.
I am convinced that even though J is a powerful, general-purpose
language, it will stay a specialist's tool, as long as this reference
problem isn't solved. The paradigm shift required to grasp the basic
concepts of J (or APL) is a significant barrier. Much of this barrier is
simply the lack of common semantics between the learner and the
documentation. Today, only the truly dedicated are willing to expend the
energy to overcome this barrier.
Information on J comes in many forms; PDF documents, Forum posts, Wiki
pages, MS Word docs, HTML docs, and more. Search engines have solved the
problem of indexing all of these kinds of documents into a single index,
allowing a single search to find keywords and return documents in all of
these formats. The problem we face is the inverse of that - how to allow
a neophyte user to add keywords (tags) to all of these formats so that
it gets put into the search engine. Like the search process, a single
simple step should allow a user to tag keywords onto the information he
finds. Ideally, the find and tag operations could be performed in the
same process.
So that is the challenge for J, if it wants to truly expand its user
base. Some out-of-the-box brainstorming may be required to come up with
the solution....
Skip.
.
.
.
PackRat wrote:
Hi, I've got a couple of doc nitpicks from a "beginner" perspective:
(1) Could the Dictionary *please* have "Related Words" sections added
to the entries for both the monadic and dyadic forms of words? There
could be one related or several related words--or perhaps no related
words. I'm thinking primarily in terms of cross references to related
words (for example, box/ace) or to opposites and inverses (for example,
take/drop, box/open, square/square root, infinity/negative infinity)--
of course, these should be hotlinked in the online version.
As a beginner, I have the darndest time trying to find related
terminology. The Dictionary seems to indicate *no* relationships
between the words contained in it (that is, no "see also" references).
Perhaps there are relationships, but they certainly do not seem at all
intuitive to a new user. (I'm aware, of course, that there is a
relationship between inflected forms, but that symbolic relationship is
not always obvious in the terminology used.)
(2) The Dictionary (at least its PDF print version) needs two major
additions to its indexing: (a) the terms currently used may be quite
exact, but many of them are not the first word that may come to mind
for the concept involved; the index of words needs to include
additional alternative English words for some of the terms chosen as
well as inverted forms (that is, both "natural logarithm" and
"logarithm, natural")--a good index has *lots* of entries; and (b) an
"alphabetical" index of the primitives in ASCII order for quick
assistance to new users in figuring out sequences of verbs, etc., found
in published scripts, electronic books, documentation resources, and
forums. (I've had to create such indexes for my own learning purposes,
but I don't think new users should have to do that for themselves.)
The "Ndx" does fine with alphabetical entries, but there's plenty of
room along the top of the page to include the punctuation symbols as
well. To truly be a "master" index, it should include the "base"
symbols; the inflections would be included under each base symbol.
Curiosity question: how come the ijt and ijs entries in "Ndx" aren't
hotlinked?
(3) EXAMPLES! EXAMPLES! EXAMPLES! Advanced users can easily get by
(that is, "Oh, I see!") with only a single example or two, but new
users need lots more. This is by far the most common complaint among
new users of *any* software, whether application, language, or
whatever. What I think is needed is an additional "Dictionary of
Examples", where there might be, say, 10-15 examples for each verb,
adverb, control, foreign conjunction, etc. These examples would use
"real" data (that is, avoid the iota/integers generator), both numeric
*and* textual, and would illustrate all sorts of cases where this verb
(etc.) might be practically used. Perhaps there might be a separate
"dictionary" of examples for the verbal commands in the "Definition
Summaries" (such as wd, gdbmp, colhdr, rplc, etc.) What would also be
extremely useful for newer users is a small collection of "real world"
type application script examples that would have *extensive explanatory
commentary*. I'm not looking here for multi-hundreds of lines of code
(which I guess, based on forum messages, is what sophisticated
commercial application scripts must seem to have), but for simple
scripts that might be up to, say, 20 to 50 lines that illustrate a self-
contained "mini-application" (even something as simple as reading a
disk file, massaging the data in some way, and writing the revised data
back to disk--this is a basic operation that is fundamental to most or
all other application scripts). The forums and such provide lots of
elegant single-liners and such, but there's little about the preferred
method(s) of creating application scripts: what should be at the head
of the script, how to arrange code for best understanding and
maintenance, and what code and cleanup should be at the end of the
script.
(4) All online documentation should also be available in PDF files.
(Some is, some isn't; some current PDF's may be official, some may be
"unofficial".) There should be "Print PDF" buttons associated with
each online document.
(5) I'm a librarian, but I was a former (35 years ago) elementary
school teacher and have done some teaching at the college and adult
level, too. These experiences reinforced for me the values of
simplicity and clarity in the learning process. The current problem
with J is that, with all the current documentation and such, one jumps
into the middle of the language. There is no real "beginning" aspect
for brand-new users. Because J requires a paradigm shift in thinking
(compared with other programming languages), I feel that it is
absolutely necessary that J have a new additional set of documentation
designed specifically for "beginners" that takes things "slow and
easy". Much of the content could, of course, be derived from some of
the current documentation--just re-worded, re-phrased, and simplified,
with lots of examples.
By the way, if anything above is misphrased or seems to be a
misunderstanding of J, please remember that I'm a beginner to J, and
I'm still learning little by little as I have opportunity.
There has been discussion about making J more widely known and used. I
think that "new user helps" along the line of what I described above
could be useful towards reaching that goal.
Harvey
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
