I’m hoping you’ll find the documentation of the new release of Base to be much better in this regard. There’s none of the Std0 nonsense, for sure (and we hope to have that fixed in the Core documentation soon as well.)
Thanks for the nice words about RWO. And you’re certainly not wrong that a lot of the current documentation is hard to navigate.
y
@perry, I’ve had similar experiences. @Yaron_Minsky, this part of what perry described is the sort of thing that I was referring to re modules:
Also, if you start from https://ocaml.janestreet.com/ocaml-core/latest/doc/ and start clicking through to core thinking you can find Hashtbl there since RWO explains Hashtbl is part of Core, you’ll rapidly get confused, as you first hit what seems like a dummy page, then click through to something mysteriously referencing Core__.Std0, and then to a page that doesn’t reference Hashtbl.
So that is being addressed. I took your comment that current toolchain work is intended to
make it possible to generate simple documentation even for APIs that were built on top of fairly advanced uses of the module system.
to be part of the work to address this issue. The fact that people inside and maybe outside Jane Street are devoting money and time to this is something we can all appreciate, I feel, and I can easily imagine that it might have benefits for other projects’ documentation as well.
Indeed, it would be nice to see Base come with more documentation, although one can see that some effort has already been done. As far as I’m concerned, I think the main missing part is a synthetic outline of the library (at the beginning of the main documentation page, as @dbuenzli does in his great libraries) as well as a rationale for its overall structure and most important, systematic choices; and finally an explanation of the most common uses a user may make. This would give a nice entrypoint.
Secondly, although it’s not about Base stricto sensu, it’s not necessarily easy to determine how use JS’s ppx’es with ocamlbuild. You could answer that you expect jbuilder to be used altogether, and that these ppx’es wouldn’t be a problem anymore, but as of now, jbuilder is still young and does not seem to support Menhir entirely (see jbuilder Github issues) for instance.
All this is not meant as a negative criticism but, hopefully, as pointers to parts that you may wish to address with your newly-hired technical writer. All the best.
For what it’s worth, building Jane Street’s PPX’s with ocamlbuild is very easy. If you install Core, you’ll also get a “corebuild” shell script that is a simple shell wrapper around ocamlbuild that sets up all of the standard JS syntax extensions, along with some other useful settings:
#!/bin/sh
ocamlbuild \
-use-ocamlfind \
-pkg core \
-tag "ppx(ppx-jane -as-ppx)" \
-tag thread \
-tag debug \
-tag bin_annot \
-tag short_paths \
-cflags "-w A-4-33-40-41-42-43-34-44" \
-cflags -strict-sequence \
"$@"\
Actually running the inline tests requires a little more, but there’s a discussion of this here:
None of this is a replacement for good docs, of course. It’s not obvious to me where the ocamlbuild-specific docs, should go, though.
y
Your post is great about stdlib and I just would like to put an other point to precise
on why the core team did not lot of works about the standard library.
Currently, OCaml is used by the MirageOS project. Obviously, it used in this project because we have a reliable type system, a modular system too but the weight of caml runtime is important too (when you want to make the smallest unikernel) - including the stdlib.
In this context, it’s better to have, as a third part, some useful libraries and compose them each together in one program/unikernel. Finally, we can produce a binary which correspond exactly to what you want. It seems to be a specific case for a specific project but, by this way, MirageOS provided some good and modular projects used by the community (like not be dependent on the Unix system, compile it on rasberry-pi - and others exotics architectures, use it in our web-browser, and so on).
Finally, this point is more general than the purpose of MirageOS. With OCaml, you can believe to what you expect when you compile your program to any back-end (lot of works was done on this way instead a better stdlib) and if your expecting computation diverges on what you want, you can choose an other stuff (without penalty) or, as you said, rewrite it 
! To be clear, it’s better to have choice than to have all.
Precisely, I work on a project that doesn’t rely on Core nor Base, I don’t want to use all JS PPX’s but only ppx_expect (and I don’t know how to do this), Jbuilder doesn’t seem to be able to deal with certain situations yet (which is normal), and the said discussion does not solve the problem (I will try to show an example when I can publish my code).
Perhaps every Github repo for these PPX’s could contain a self-contained documentation (as of now, the documentation for ppx_expect refers to ppx_inline_tests which refers to ppx_driver… and suddenly you have to dive into intricacies which are interesting but that take a lot of time)?
Sorry for hijacking this discussion about the stdlib…
As a first step, I would try to use ppx_jane, and see if you can get the
instructions for running inline tests that I linked to working. ppx_expect
is an inline test, so that should be enough. You should be able to use
ppx_expect without the other extensions pretty easily from there.
I wasn’t clear enough: I haven’t been able to use ppx_jane because of what I suppose are conflicts with ppx_deriving; and I also had error messages regarding ppx_bench (that I don’t use). So I had then hoped to use ppx_expect alone, hence the quote above.
But never mind, I can live without ppx_expect. My point was mainly to exhibit rough edges that may need some smoothing. As JS is promoting jbuilder, I understand that providing ocamlbuild or oasis documentation may not be a priority, but then jbuilder doesn’t seem yet to fit my use case (a pure OCaml executable using several PPX’s and several Ocamllex and Menhir files).
There’s work ongoing to fix the conflicts with ppx_deriving, so that should
hopefully get better soon. Improving documentation is a good thing, but
your primary problem isn’t documentation, I think, but the conflicts with
ppx_deriving.
Anyway, we’re definitely working on improving the docs, but if people have
specific things they want to document (especially interaction with other
tools), this is a thing we’d be very happy to see PRs for.
y
there was a plan to do this for batteries, but then Simon started his own library (containers)…
More accurately, we had long discussions about merging batteries and containers, making the result as exhaustive as batteries and more modular (like containers). It failed, in part by my fault, I think (too much in one change), but also because removing the dependency of every module on unix it would have shattered batteries’ retro-compatibility. I still regret that we couldn’t make it 
I think it was the right outcome. There’s only so much backwards compatibility one can carry around without the project becoming too heavy to evolve. There’s also something energizing about a new codebase, using design principles honed by the current climate. Had there been only one standard library, I think starting a new one would have been detrimental. But once we’re in a world of multiple standard libraries, at some point you want legacy users to keep their version, and take advantage of that clean break with the past.
If modular implicits ever happen, we may need that clean break again.
An aside: what’s the status of modular implicits? They sound very cool.
Sometimes, I am thinking about releasing batteries’ modules one by one, with the least dependencies possible.
That would require a significant update of these modules (a bit like… well… batteries 3) because right now they are quite interdependant. The question is, would the result still be called “batteries”, or would we have yet another fork?
also, would that be different from containers? or would it aim to be backwards compatible with current batteries?
That would be a fork, or at least a different way of releasing batteries.
Like with each batteries release there would be a minibat release.
Minibat being a smaller, cut into pieces version of batteries, with many fat removed.