From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Original-To: caml-list@sympa.inria.fr Delivered-To: caml-list@sympa.inria.fr Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by sympa.inria.fr (Postfix) with ESMTPS id B6E237F89E for ; Thu, 3 Apr 2014 11:49:24 +0200 (CEST) Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of daniel.buenzli@erratique.ch) identity=pra; client-ip=74.55.86.74; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="daniel.buenzli@erratique.ch"; x-sender="daniel.buenzli@erratique.ch"; x-conformance=sidf_compatible Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of daniel.buenzli@erratique.ch) identity=mailfrom; client-ip=74.55.86.74; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="daniel.buenzli@erratique.ch"; x-sender="daniel.buenzli@erratique.ch"; x-conformance=sidf_compatible Received-SPF: None (mail2-smtp-roc.national.inria.fr: no sender authenticity information available from domain of postmaster@smtp.webfaction.com) identity=helo; client-ip=74.55.86.74; receiver=mail2-smtp-roc.national.inria.fr; envelope-from="daniel.buenzli@erratique.ch"; x-sender="postmaster@smtp.webfaction.com"; x-conformance=sidf_compatible X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AvglAPEnPVNKN1ZKgWdsb2JhbAA+GoNBgkGBIMBogTMOAQEWJiiCJQEBAQMBI1YFCwsaAiYCAkcQBhuHaQgECTasHKJyF4EpjRUzB4JvNYEUBJoNhQYXjx8 X-IPAS-Result: AvglAPEnPVNKN1ZKgWdsb2JhbAA+GoNBgkGBIMBogTMOAQEWJiiCJQEBAQMBI1YFCwsaAiYCAkcQBhuHaQgECTasHKJyF4EpjRUzB4JvNYEUBJoNhQYXjx8 X-IronPort-AV: E=Sophos;i="4.97,786,1389740400"; d="scan'208";a="66190753" Received: from mail6.webfaction.com (HELO smtp.webfaction.com) ([74.55.86.74]) by mail2-smtp-roc.national.inria.fr with ESMTP; 03 Apr 2014 11:49:23 +0200 Received: from [172.20.10.2] (117-236.197-178.cust.bluewin.ch [178.197.236.117]) by smtp.webfaction.com (Postfix) with ESMTP id 67AC5226E884; Thu, 3 Apr 2014 09:49:18 +0000 (UTC) Date: Thu, 3 Apr 2014 11:49:15 +0200 From: =?utf-8?Q?Daniel_B=C3=BCnzli?= To: Gabriel Scherer Cc: Yotam Barnoy , Ocaml Mailing List Message-ID: In-Reply-To: References: X-Mailer: sparrow 1.6.4 (build 1178) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Content-Disposition: inline Subject: Re: [Caml-list] Activating wiki on ocaml github Le jeudi, 3 avril 2014 =C3=A0 11:16, Gabriel Scherer a =C3=A9crit : > 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 ha= ve here. These wiki were created because the creator of these tools refused= to write proper/good documentation and said let's "crowd source" the docum= entation to a wiki, a behaviour that should immediately raise red flags.=20= =20 =20=20 > If the documentation need to be synchronized with the compiler's evolutio= n, 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 se= ctions 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 t= ext with very precise references see: http://caml.inria.fr/pub/docs/manual-= ocaml-4.01/ocamldoc.html#sss:crossref