Raul, I hope the search boxes on jsoftware.com and its wiki aren't also prevented from searching it!
Pascal, that's an interesting point. If I hadn't kept searching I probably would have only ever used the version you wrote up in the wiki. Joe, I agree that the quality of the documentation is excellent. But it can be hard to find what you're looking for. The search method you use is pretty close to what I use as well, but I think we're somewhat unusual compared to an "average computer language user" who might give up more easily. Here's an example of (in my opinion, very nicely done) documentation for community-generated addons for a programming language: http://package.elm-lang.org/ In that search bar, you can type a phrase and watch the results narrow before your eyes. Example: type 'sig' and see that not only does it find results where 'sig' is in the text (but not the title) but it also shows a warning that some packages are only compatible with a particular version of the runtime. One can imagine other nice-to-have documentation-discovery features, such as user ratings or showing dependencies and such. To satisfy my own itch, I started working on an analog to Matlab's interactive "help" function, which currently just returns names and their locales: https://github.com/hoosierEE/jhelp It's not much yet, but hopefully can be extended to include some of those "nice to have" features. On Fri, Dec 4, 2015 at 4:04 PM, Joe Bogner <[email protected]> wrote: > In general, I'd say that J has excellent documentation. It's well > above average for non-main stream languages. That being said, there's > certainly always room for improvement in documentation - especially > when things are continuing to improve and change. > > I had the same experience as Alex but eventually found my way to an > answer, so I'll share my steps below. > > 1. Search for md5 on code.jsoftware.com - first hit pascal's. Try it, > but ran into issues with some missing definitions (e.g. listhash) > > http://code.jsoftware.com/wiki/User:Pascal_Jasmin/SHA_1(2c20)2_and_MD5_for_windows > 2. grep my addons folder for md5 in *.ijs... find out that it produces > the wrong result on j64 > 3. Search for md5 on http://www.jsoftware.com/forumsearch, see issues > with md5 on j64 > 4. Move on to next result of md5 on code.jsoftware.com > http://code.jsoftware.com/wiki/System/ReleaseNotes/J802 > > I typically try the following resources when looking for an answer: > > 1. Search http://code.jsoftware.com/ > 2. Search http://jsoftware.com/ > 3. Search forums http://www.jsoftware.com/forumsearch > 4. Search my local J installation *.ijs > 5. Email the mailing list > > This recipe has worked pretty well for me. I would say the > searchability is quite high - the only downside is a few places to > look. I'd rather have a few places than not enough places though > > > > > On Fri, Dec 4, 2015 at 3:43 PM, 'Pascal Jasmin' via Programming > <[email protected]> wrote: > > the md5 addon may be 20x-100x slower than gethash or my direct openssl > link. The challenge might have taken over 5 minutes to run with it. > > > > Your point about searchability is important. > > > > > > > > > > ----- Original Message ----- > > From: Alex Shroyer <[email protected]> > > To: [email protected] > > Sent: Friday, December 4, 2015 3:20 PM > > Subject: [Jprogramming] Addons should be easier for users to discover > > > > As Steve Yegge has <https://plus.google.com/+RipRowan/posts/eVeouesvaVX> > > pointed out < > https://sites.google.com/site/steveyegge2/bambi-meets-godzilla>, > > accessibility and marketing are what separate ideas that survive from > ones > > that pass into obscurity. > > > > One thing I think J could be doing better is making the standard > libraries > > easier to discover. > > > > Example: > > > > The 4th puzzle on Advent of Code <http://adventofcode.com/> requires > > generating MD5 hashes of a string. I've been using J for several months, > > but the first thing I found when looking for MD5 was this page > > < > http://code.jsoftware.com/wiki/User:Pascal_Jasmin/SHA_1(2c20)2_and_MD5_for_windows > >. > > It wasn't until much later that I discovered I already possessed on my > > computer a J addon with this functionality, in the form of > > *addons/convert/misc/md5.ijs*! > > > > > > This is an accessibility problem. In my ideal world, the top result for > > googling the phrase "J md5" would be a page from jsoftware.com > containing > > documentation for the above addon, with pretty formatting, syntax > > highlighting, example uses, and links to related addons. > > > > My realistic expectation is that typing queries such as "md5" or "ssl" > into > > the search bar on jsoftware.com (or the code.jsoftware.com wiki) would > at > > minimum return links to addons containing those words. Currently, the > > closest hit (other than wiki user Pascal Jasmin's page) is the j802 > release > > notes page <http://code.jsoftware.com/wiki/System/ReleaseNotes/J802>, > which > > mentions cryptographic functions exist, but provides no link to further > > documentation. > > > > If the J scripts library is supposed to be like the .NET Framework or > CPAN, > > it needs to be more discoverable. Indexing addons for keywords would go > a > > long way toward this, I think. > > > > > > I'm posting this complaint because J is my preferred language, and it > makes > > me sad to see it losing mindshare to products like Matlab. > > > > Sincerely, > > Alex > > ---------------------------------------------------------------------- > > For information about J forums see http://www.jsoftware.com/forums.htm > > ---------------------------------------------------------------------- > > For information about J forums see http://www.jsoftware.com/forums.htm > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
