Re: [Caml-list] Activating wiki on ocaml github

["Daniel Bünzli" <daniel.buenzli@erratique.ch>]

Le jeudi, 3 avril 2014 à 11:16, Gabriel Scherer a écrit :
> Color me unconvinced. My experience with wikis has been mild at best.
> There exist wikis for Camlp4 and Ocamlbuild (
> http://brion.inria.fr/gallium/index.php/Camlp4 ,
> http://brion.inria.fr/gallium/index.php/Ocamlbuild ) that have seen
> little contributions outside the core maintainers, and the content is
> often ignored as it is not part of the official manual.

Yes terrible idea. Though I'd say that's not exactly the same case as we have here. These wiki were created because the creator of these tools refused to write proper/good documentation and said let's "crowd source" the documentation to a wiki, a behaviour that should immediately raise red flags.  
  
> If the documentation need to be synchronized with the compiler's evolution, I
> suspect the best place to put it would be either along the compiler.

The real answer seems to be: literate programming. Maybe more realistically ocamldoc'ing the interfaces and writing cross-referenced [1] additional sections in there at the end of the files could be a good start.

Best,

Daniel

[1] ocamldoc's link syntax combined with its xref syntax allows to author text with very precise references see: http://caml.inria.fr/pub/docs/manual-ocaml-4.01/ocamldoc.html#sss:crossref