2025 Documentation best practices

Not fully false of course :wink:

I have started writing my documentation in odoc + mdx in the end, for the benefits of having code that I can guarantee is in sync with my tutorial in the end. So I’ll probably end up opening issues.

I don’t think there’s anything major missing, it’s just a bunch of small papercuts that make it discouraging over time. For instance, right now, I’m struggling with mld + mdx – though admittedly it’s not really an odoc problem.

If you’ve ever tried to write documentation in e.g. docusaurus, everything you may want to do is possible and with relatively little effort (except interacting with the OCaml ecosystem, and provided you are somewhat familiar with javascript in the first place). The thing is, there’s an entire team of people at Facebook who’ve been paid for years to create and maintain the thing. If anything, the fact that odoc is so good given the comparative amount of maintainers is incredible!
I guess what I’m saying is more: maybe we (as a community) should focus with enabling interop with existing tool rather than try to re-implement every good idea into our ecosystem.