I vote for hyperlinking everything. That way if I didn't know something or had
forgotten it with one click I could learn or relearn it.
> Date: Fri, 15 Jan 2010 08:25:13 -0500
> From: devon...@gmail.com
> To: programming@jsoftware.com
> Subject: Re: [Jprogramming] The Ambiguous Dictionary
>
> We discussed this at NYCJUG this week - I offered some examples of how
> explanation for beginners is better done: one is the old APL reference by
> Sandra Pakin, another is an example in Perl - I can't find the example I
> used right now but search on something like "perl key" or see
> http://www.cs.mcgill.ca/~abatko/computers/programming/perl/howto/hash/ or
> http://www.devdaily.com/perl/edu/qanda/plqa00015/ .
>
> The Perl example I showed was good because it allowed user responses to
> elaborate on the explanation and examples shown.
>
> The Pakin reference manual was useful because it has a definition on one
> page and some examples on that page and the facing page.
>
> On Thu, Jan 14, 2010 at 6:23 PM, Dan Bron <j...@bron.us> wrote:
>
> > Skip Cave wrote:
> > > What is needed is a "training wheels" mode where each Vocabulary entry
> > > has lots of examples, common usages, explanations of terms, etc. Same
> > > for the Dictionary, which should explain each definition as if the user
> > > has not read anything about J before this instant (which will often be
> > > the case). This is for the reader who doesn't start at the beginning,
> >
> > Ah, ah. I think you have struck the heart of the matter. There is a J
> > user base who finds the Dictionary's terseness an impediment (I did for a
> > very long time), and another who find it a benefit (like I do currently).
> >
> > The insight is that the former group turn to the Dictionary, because that
> > is the only reference they have. If they didn't have to read the
> > Dictionary, they wouldn't. If they had somewhere else to turn, they would.
> > If this group had another option, the DoJ's terseness would be irrelevant.
> >
> > If we consider Skip's idea in the light of Raul's earlier question:
> >
> > > Is there some kind of problem with tutorials and other works
> > > providing this level of redundancy?
> >
> > we realize that it is not incumbent upon JSoftware to provide this option.
> > Their job is to publish the normative reference for the language and the
> > official implementation. And that's what they spend their time doing
> > (thanks!).
> >
> > So someone else must furnish the verbose alternative Dictionary. I note
> > that those who want it, are in exactly the wrong position to provide it.
> > I further note that the community (this community) has often furnished
> > itself with related material (labs, books, demos, the Wiki). So there's
> > the gauntlet, on the ground...
> >
> > -Dan
> >
> > PS: Maybe we could do this communally, rather than burdening an
> > individual. If I started a Wiki area that was formatted like the
> > Dictionary, and maybe created a seed Vocab entry or two, would others
> > contribute to completing it?
> >
> > Remember that the goal is still to create a reference, not a tutorial. So,
> > for example, we'd have an entry on cut, but not on parsing strings (though
> > we could link to other parts of the Wiki for this). The entry would have to
> > describe what cut is, and all its subtleties, in an accessible way, but not
> > how to use it. Each entry must attempt to be both complete and correct
> > (though still deferring to the real DoJ in the case of any conflict). I'm
> > not sure this would be an easy thing to do, so it's worth considering before
> > you commit to the project.
> >
> > Also worth considering is that the value of a reference is not a linear
> > function of its completeness. A 25% done Dictionary is not 25% as valuable
> > as a completed Dictionary, because if you can't trust it, you won't turn to
> > it in the first place. Furthermore, community projects also have this "non
> > linear" aspect, and if this isn't a very visible project with lots of
> > activity, newcomers won't know about it, and veterans won't contribute to
> > it, and it will die, and we'll be back in the same boat.
> >
> >
> > ----------------------------------------------------------------------
> > For information about J forums see http://www.jsoftware.com/forums.htm
> >
>
>
>
> --
> Devon McCormick, CFA
> ^me^ at acm.
> org is my
> preferred e-mail
> ----------------------------------------------------------------------
> For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
