Ian Clark <earthspotty@...> writes:
>
> > Being completely new to J, I have new eyes and could, perhaps, add changes
> > to the document which would enable the next reader to have a smoother
> > session with that document. Shall I do that? Or should I file a report
> > somewhere with these changes?
>
> I have a professional interest in novice uptake of computer tools, J
> in particular -- and what constitutes appropriate documentation. "New
> eyes" are precious -- and we're apt to forget how precious. And
> transient.
>
> The rest of us have Rumsfeld Syndrome over how a novice views J
> documentation ("unknown unknowns"). It very much depends on where the
> novice is coming from, if it's not from APL. Henry's JfC explicitly
> addresses C programmers, and from my recollection of C programming
> it's spot-on. We need others like that.
>
> Can you please keep notes of your stumbles with the existing
> documentation? Feel free to pm me with them. There will be questions
> you'll have that you simply would not think to ask in a couple of
> months. This does not invalidate them.
>
After having gone through much of the documentation provided in a local J
installation (excepting JFC and PHR), here are the issues (relating to
documentation for one who is new to J) that stick out most:
* There is almost nothing which references the z library
RESULT: As one who is beginning to explore the language, I cannot develop a
comfort level of relying on the library. I spent significant time tracking
down
a problem while I was going through the documentation. I had picked up use of
the 'names' verb from that library. And because of a flaw in its
implementation
(combined with my incorrect guess that it was a 'wrapper' around the foreign
conjunction '4!:1')... so, I'm confused. What is the technical definition, or
goal, of that verb? Since there is no definitive documentation for the
library,
one can only guess about the purpose of its defined verbs. The installed
documentation lists a few of the library's entries... but the objective in
those
books is different from a definitive resource. My biggest surprise is that
there is almost no mention of the z library in the Dictionary which is supposed
to be the *primary* reference.
* There is no quality discussion of the JHS IDE
RESULT: Lots of questions. What are the purposes of the "scratch" and
"scratch ..." menu items? What is 'jfif' for? On the J Active Library page,
something as small as incorrect case prevented a link from being effective:
www.jsoftware.com/jwiki/addons should have the an uppercase 'A' in the 'addons'
part of the URI. I was able to locate and correct that on my local version.
And the effort paid off in terms of gaining a better understanding of the
system
overall... but took my focus off of my study of the language... while I tried
assessing the problem with the IDE.
* The online resources feel very scattered.
That being said, I am still very excited about learning J. I see the potential
for the development tools to mature and to fulfill a much-needed requirement.
But, maybe, my expectations were too high.
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
