# OCaml Documentation Open Thread **URL:** \ **Category:** Ecosystem\ **Created:** [April 11, 2018, 11:32pm UTC](https://discuss.ocaml.org/t/ocaml-documentation-open-thread/1841 "2018-04-11T23:32:30Z")\ **Posts on this page:** 1\ **Showing post:** 138
**Author:** ![dbuenzli](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ocaml.org/dbuenzli/32/18_2.png) [@dbuenzli](https://discuss.ocaml.org/u/dbuenzli)\ **Post date:** [July 26, 2018, 12:09pm UTC](https://discuss.ocaml.org/t/ocaml-documentation-open-thread/1841/138 "2018-07-26T12:09:03Z")
> [@perry](#): > > but even plain text files of good documentation We even have better than that. We have the [`ocamldoc` language](https://caml.inria.fr/pub/docs/manual-ocaml/ocamldoc.html#sec351). It allows to have your documentation exactly where it is needed, in `mli` files, and will carry itself if you move your sources around. The ocamldoc language is a fully featured document markup language with sectioning and _checked_ cross references to sections and API entry points. Doing manuals and tutorial inside `.mli` always felt a bit cumbersome but is entirely doable as can be witnessed in many of my packages (see [this one](http://erratique.ch/software/vg/doc/Vg.html) for example). The good news is that nowadays we will gradually be able to write those larger pieces in seperate `.mld` files. Code sample extraction is not there yet but I hope we can have a [simple design](https://github.com/ocaml/odoc/issues/130) implemented soon rather than having these discussions. The other good news is that as a programmer, the effort you need to provide in order to make the documentation you write in this language available to end-users is this: **approaching zero** : - If you are using `topkg` or `dune-release` (assuming they didn’t kill that workflow), publishing your docs online on github is a `topkg distrib && topkg publish doc` away. - Distributing this documentation with your package releases is also _automatically_ done if you use `topkg+ocamlbuild` or `dune`: these systems compile and install the right files which `odig` can then pickup in order to generate cross-referenced documentation for all the packages that are installed in your `opam` switch and allows you to peacefully read all this wondefully produced documentation offline with the stylesheet that suits you. One might complain that the ocamldoc language syntax is none of these alternative document markup languages whose popularity or existence came after `ocamldoc`’s birth but if you ever tried to write a polymorphic variant in a markdown code span you will be glad that ocamldoc’s language isn’t that one. I understand the `ocamldoc` language is one more thing to learn as a newcomer but it’s not hugely complex, it’s there, it works with the advantages highlighted above and an aspiring OCaml working programmer shall meet it quite soon anyways since there are thousands of lines of documentation in hundreds of projects that are using it. --- _[View the full topic](https://discuss.ocaml.org/t/ocaml-documentation-open-thread/1841)._