Outreachy December 2022

[jbeckford]

@dbuenzli

Why don’t you use .mld files for that ? You get a decent edition language and checked cross references into your API reference. Not to mention latex maths which was merged a few days ago.

Definitely use .mld files for API reference. You can even do some explanatory, linear documentation like I did with dirsp-exchange-kbb2017. But I haven’t found .mld files to be good substitutes for a linear documentation site like Diskuv OCaml documentation. Honestly, I doubt I could produce that site with .mld files (or the other two I mentioned), but I’m willing to be proven wrong.

The best counterpoint I know of is the odoc documentation site itself. It is well-written, linear and a good example of dog-fooding. It is also plain text combined with OCaml source code, and once you stray a bit from that (ex. diagrams, capturing interactive sessions, transclusion, etc.) you quickly see the limitations today. Continued below

@dbuenzli

.mld files have a zero cost publishing experience for developers, just write the files, let the eco-system do the rest (ocaml.org and odig). For end users it makes it up for an extremely reliable doc hunting (and viewing) experience: either lookup on ocaml.org or via odig doc for the version installed in your switch (works offline and with the theme of your wish).

No disagreement, especially for reference documentation where the user queries for a module/package/keyword they already know. But the assumption being made is that .mld is great for tutorials, user guides and books … great for both readers and authors … so why bother with anything else? Continued below

@yawaramin

I agree, odoc and ocamldoc syntax already support fairly sophisticated documentation output, it doesn’t even need to be written in reference style, it can be in tutorial or user guide style.

A good example for a tutorial / user guide / book written in .mld / .mli would be nice! Then it can be compared side-by-side with the examples I already provided.

IMHO part of the comparison should be how easy it is to write comprehensive documentation for newcomers (or we’ll never get good docs in the OCaml ecosystem!). I can readily attest to newcomers being able to write documentation in Sphinx (much of that can be browsed on https://readthedocs.org/), so real examples, especially from non-experts, would be useful in this discussion.

I also hear scope creep. Is odoc a tool for reference documentation (where I know what modules/keyword I am looking for, and can ask the tool to do a search) or for linear documentation (where the docs tell me about things I don’t already know), or both? Perhaps it would be better to focus on making odoc a great API reference document tool (which I think it is, alongside odig and the search bar of v3.ocaml.org), and delegate to mature tools for linear documentation that are designed to work with existing API reference tools? (hint: Sphinx)

@dbuenzli

It seems it has become some kind of hobby to add new backends to odoc but meanwhile after almost 8 years in existence there are still problems in the base HTML renderer and important unresolved issues like a convention to be able to add images or code extraction. I think it would be a better idea to focus on the existing in odoc and make it great rather than add new backends.

Yikes; multiple things you mention are troubling.

• Why is it either-or?
  • This thread is about what Outreachy can do with assigned mentors. I believe the Sphinx (Python) plugin portion can be done by Outreachy; I’m not 100% confident about the odoc side but it seems significantly simpler than the existing Markdown backend PR (which is why this would be done with a co-mentor). But … it sounds like the suggestion is to do an Outreachy project to solve 8 year old issues instead. Something doesn’t sound right. Perhaps someone can post a link to those issues?
  • It sounds like the suggestion is to stop all feature development of odoc to fix 8 year old issues. But that begs the question why the mentioned issues are there after 8 years. Perhaps they are not critical, too complex, etc. Or perhaps we really should drop everything and fix them.
• I acknowledge that often adding new features increases the technical debt with the existing code. But the new backend I am suggesting delegates all of the rendering to the Sphinx side, so it should not increase the technical debt of odoc.
• I question why we want to duplicate features from other documentation tools (Sphinx, or Markdown + static site generators) when we have limited resources. For example:
  • I was able to produce a documented walkthrough of an OCaml cram (expect) test using plain, readable Sphinx that works today. (I also use similar functionality from MDX in Markdown for projects that only need one or two doc pages)
  • If I’m documenting an HTTP API, I am going to reach for the Sphinx httpdomain plugin instead of re-inventing the wheel. Ditto for graphviz and PlantUML diagrams. I don’t want to wait another 8 years!
  • I can type Markdown and Sphinx documentation in Visual Studio Code and get almost instantaneous visual feedback in the code editor preview. That makes writing documentation enjoyable and almost effort-less.

So for now I’ll wait for some non-expert .ml{i,d} generated examples of tutorials, user guides or books.

This sounds like it needs a new thread!