2025 Documentation best practices

What exactly do you mean by that :–) ?

They keep on improving. You can now have media assets, tables, maths, etc. You can extract code out of them. Language wise they are full on par with what markdown plus extension would provide. And most of these markdown systems miss a crucial feature needed for documentation maintenance: checked cross-references, both between your .mld pages and in your API reference (don’t underestimate how important that is).

If it’s the default stylesheet that puts you off just make your own (I do). Also that doesn’t seem to be your case but if you don’t have the time so setup a website they make the path to publication exceptionally easy (publish your package on opam, they will be on ocaml.org).

I reworked the cmdliner docs recently which have all of what you mention except for blog posts.

The thing is that you need to put yourself in the shoes of your users. They are unlikely to use only your library but a couple of them, it’s a pain if each of these has its own home and way of presenting the documentation.

For myself I’d also be particulary annoyed if a library doesn’t allow me to work offline. Just for example this spring we had exceptional snow falls in my area, that meant no cellular network for one day, no electricity for two and road cut for three. These are perfect time to focus :–) And the meteorologists tells us these extreme events are not getting any rarer (in fact in a nearby valley, a village just got wiped off the map in a torrent of ice and mud :grimacing:).

So keep the offline documentation experience living!

4 Likes