New site for Jane Street Open Source libraries

#1

We recently created a new site to centralize information about our open source libraries. You can find it here: http://opensource.janestreet.com. If nothing else, it’s a good place to get links to our API docs.

If you have thoughts about how we can make these resources more useful, we’d be glad to hear about it!

y

12 Likes
#2

Nice looking and quick :smiley:

Why is ‘core’ a higher level tier as ‘base’?
Quite confusing naming, imho.

Thy

#3

The bottom of janestreet.com has a “Code Library” link that points to https://janestreet.github.io/, but it looks like that page is either being deprecated in favor of this new site or perhaps is just out of date. It might be good to either replace that link, or add a link to this new site, depending.

It would be nice to have some way of navigating to different versions of the documentation. So far as I can tell, if I go to https://opensource.janestreet.com/base/ and click the “API Docs link” there is no sequence of links I can click that will get me to an earlier version of the library. I either have to guess the URL scheme or chop the URL down to https://ocaml.janestreet.com/ocaml-core/ and navigate from there. Possibly this is a limitation of the documentation generator.

In a similar vein, it maybe would be useful for the documentation page itself to have a link to the changelog.

#4

Good suggestions. Thanks! We’ll take a look at those.

y

#5

On documentation: I would suggest that looking at the sort of official documentation one finds for the Python and Ruby would be a good model for documentation in OCaml. Not only is the layout often clearer, and the information more easily found, but it’s also much more nicely formatted. The latter is surprisingly important — the difference that mere reformatting has made to the Coq documentation between Coq 8.7 and Coq 8.8 (which now uses Sphinx) is remarkable. You would not think this would make such a difference in readability, but it does.

It would be wonderful if the documentation for Core and Base were to eventually look more like, say, this: https://ruby-doc.org/core-2.5.0/String.html or like this: https://docs.python.org/3/library/decimal.html

#6

Oh, and btw, although I understand why there’s a complicated set of module relationships in things like Base and Core, it would be nice if the documentation shielded the reader from that information more, so that if you wanted to look up how something worked you didn’t have to hunt around to figure out where it actually was implemented but could just look in one place.