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
