OCaml Documentation Open Thread


#63

I just had a chat with @antron about this very thing, and will be taking a look at the odoc source to see how hard it would be to merge the two. Hopefully we can join forces productively :slight_smile:


#64

I forgot to mention one feature of the Owl documentation that wouldn’t be obvious unless one happened across certain pages. Sphinx allows one to embed LaTeX in HTML documentation (example). It’s a nice feature for mathematical libraries.


#65

Note that the ocamldoc language allows to provide LaTeX specific content via the {%latex: %} directive. The original semantics is to only interpret the content if you target a latex backend. I’m not sure if that’s used a lot though.

A cool odoc hack would be to add a mode where these sections are not dropped but inserted in the document within $ delimiters. Now plugin the MathJax script in the page and you have your maths.


#66

Untangle the module spagetti so that functors, includes and signatures work properly and are linked.

I would just like to emphasise quite how difficult this is. One of the reasons OCaml’s documentation tooling is not in as good a state as other languages is that OCaml’s module system is just about the most expressive system around for building APIs programmatically. Getting cross-references right in OCaml amounts to re-implementing the module system. This requires a very good understanding module system, and even then it is difficult. I know the language pretty well, and my first attempt – which is what currently drives odoc’s resolving – is fundamentally flawed in a number of ways and will need a large rewrite before it can satisfactorily handle libraries like Core. Unfortunately I do not have the free time to do this rewrite, but there are plans afoot for OCaml Labs to take up the gauntlet.

people working on one tend to severely underestimate the other

I wouldn’t say that we underestimated the amount of work needed to make the UX nice, we just never had the man power to work on it, and the code base wasn’t in a good enough state for others to contribute. Thankfully @antron has being doing some excellent work on this front. In particular, he has been doing the necessary untangling and design to make it easy for people to contribute on the UX side without needing to understand the complexities of the resolving engine. Hopefully this will lead to some big improvements on this side of things.

Hopefully we can join forces productively

That sounds like an excellent idea. docre looks like it has nice UX features which odoc sorely needs, and joining forces will save you from having to try and solve the aforementioned reference resolving problems.


#67

BTW, as we’ve been discussing documentation technology quite productively, let me switch to a plea for a particular piece of content, in this case, good ppx documentation, which I mentioned near the top of this topic.

I would try writing it myself, but it’s something that has proven too complex for me to fully puzzle out on my own. There are some blog posts, a few other bits, and a bunch of libraries people seem to have built to make using ppx easier, but it would be amazingly cool if someone could put together a real manual (including significant examples) for the whole ppx ecosystem.


#68

odig is a great tool but I suspect it comes down to being able to find it and as importantly the development status: Version 0.0.3 gives the impression of being for wizards only. I suspect an integrated documentation ecosystem with odoc and odig and a simple 3 line quick start would make all the difference.

In fact my feeling is that creating a centralised documentation ecosystem with some start up documentation would in itself move thing forward. This would include:

  • A guide to writing great docs
  • A howto on documenting libraries including how to use the various features of the tools and a style guide
  • Document generation with odoc and jbuilder
  • Browsing installed library APIs with odig

#69

For wizards ? Well I’m not exactly sure where you get this impression from.

  1. Odig is mentionned on the ocaml.org documentation page.
  2. This leads you to this page which has exactly the 3 lines quick start you requested for which are the only commands you really need to issue.
  3. If you followed another track and get to the README you have this section which repeats the above and has more.
  4. If you are still hooked you are advised in that readme to invoke odig help basics which is a short introduction to the tool.

I gladly take any criticism if things can be improved but frankly I’m more inclined to think that people simply no longer read (which echoes my last comment here). If it’s too much for people to consult the webpage/README of the tools they use I’m afraid there’s not much that can be done.

The tool is not finished and I expect to iterate a few more times on it (and soon enough), but as odig help mentions it is “a usable work in progress”.


#70

It’s true. I would say is that the reason people don’t read as carefully is that modern pages are designed to visually guide the reader.

That said odig is a good example of surprising choices. When I am on the odig page I’d expect the Documentation link to take me to the cli documentation, rather than the documentation for the top level.


#71

Point taken. But it’s not a choice it’s rather an unfortunate artefact of my web publication system which is geared at making webpages pages for all these libraries.

One error that I have consistently made these last years is to write extensive documentation in manpages (See the sections in odig help, topkg help). It’s a bad idea as it doesn’t allow for web cross linking and make online discussion/reference painful (can only link in the sources… since I don’t publish html rendering of these).

Nowadays that we have odoc manuals, I’ll change that and keep the manpages to a minimal and refer to a proper online manual for more extensive documentation. Bonus point with that strategy the “suprising choice” of the documentation link you mention will point to the manual.


#72

Note that if someone has an incorrect impression, it’s usually most productive to figure out how they got their misapprehension, and how to prevent others from getting it.

Blaming the reader for not paying attention is possibly reasonable, but will not actually fix the situation (since you cannot fix humanity, or at least, that’s likely more the domain of people doing gene editing than computer science.)

Thus, if the goal is to enlighten more people, it doesn’t help to note that humans are flawed (which they most assuredly are), and the right thing to do is to figure out how to enlighten people in spite of their flaws. (If one’s goal is not to enlighten people, then working on documentation is unnecessary in the first place.)

And it is absolutely true: people will fail to notice things right on the page for all sorts of weird reasons. This is why good typography, careful writing to draw attention to the right things, redundancy in how you explain things (because people don’t perfectly absorb information the first time and sometimes even fail to register whole sentences while reading) is important.


#73

Which is precisely why I’m asking what can be done and @wokalski provided a good remark.


#74

Why not both? ocamldoc has man page output, so it should be feasible to translate one into the other. While having no doc online is very annoying, opening some man page to only see “consult the online documentation” is beyond frustrating (especially when you’re in a train).


#75

Indeed. If you can generate both from one set of sources, it’s nice to give people the option both ways.


#76

Why not. I’m not sure that’s a priority of the odoc project though.

Well since this will be an odoc manual and you will have taken care of installing odig before boarding. It will be right there an odig doc pkg away for your reading pleasure.

Note that for this reason I think we should try to make sure odoc manuals can provide enough support so that e.g. owl can write it’s manual in it rather than use another system. As a developer you then know that once you have your package installed, all the docs are there aswell and you can take you train with peace of mind. It also provides a hassle-free way for package devs to distribute their documentation.


#77

This seems like a great idea.

Maybe it be ideal would be if there was syntax that allowed one to specify an optional text string to use instead of the LaTeX when LaTeX processing is unavailable. In many cases one would write the ocamldoc so that no alternative text was necessary, but this strateg would allow one to specify a (presumably uglier) text substitute for the LaTeX for display in editors, utop, etc. I would think this would be fairly easy to build in if one were setting up a general LaTeX ocamldoc processing system in the sort of way that @dbuenzli suggests.


#78

As a response to this (and other replies on this thread) and still in the spirit of DocJam, I came up with this:

It touches the topic of how to write docs, how to write good docs, tools for generating docs, and how to put documentations online. I’m not sure how well this would be received but I agree that to reach a consensus, a written document is necessary.

The intention is that this document can be referred to when you’re writing or reviewing docs, or asking contributors to write or review docs.

Note that there may be mistakes and misguided recommendations on those guide at its current state because it’s mostly my own limited knowledge, but I figured I’d put it up anyway to give us something to improve upon. I’d love to invite folks here to improve it by opening issues/discussions and contributing PRs to that repo.


#79

This is absolutely terrific, and should be linked to by the odoc repo. I feel like we need a best practices resource, and this could be a part of that (either linked from it or copied in).


#80

There is a partial overlap with the ocamldoc manual, but more importantly, while this is a very good idea, I really think these kind of pages should be added to ocaml.org instead of being lost in isolated github repositories.


#81

Sure, once it is a bit more mature, ocaml.org would be a fine place to put it. But, he had to start editing it somewhere.

And @bobbypriambodo, kudos! This is a great thing to have started!


#82

Do you mean the Basic Documentation Syntax section? I originally also thought of just leaving a link to the manual page there, but I figured it wouldn’t hurt to put a markdown vs. ocamldoc comparison, since the manual page contains no such info (not that it should).

Yes, I’m very much fine with putting it anywhere that is more proper and that will get broader audience. However as pages in ocaml(dot)org would be more or less treated as an official recommendation, I think perhaps we can use another place to iron out the rough edges first. I’m happy to be told otherwise though.