From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr X-Spam-Level: X-Spam-Status: No, score=0.2 required=5.0 tests=AWL,MISSING_HEADERS autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by yquem.inria.fr (Postfix) with ESMTP id 62ABDBB84 for ; Mon, 9 Feb 2009 13:51:55 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: Aq4FAPy1j0mBrw8EgWdsb2JhbACNDYYQgRwBARYiuXKEGgY X-IronPort-AV: E=Sophos;i="4.37,405,1231110000"; d="scan'208";a="20838315" Received: from ext.lri.fr ([129.175.15.4]) by mail2-smtp-roc.national.inria.fr with ESMTP/TLS/ADH-AES256-SHA; 09 Feb 2009 13:51:55 +0100 Received: from localhost (localhost [127.0.0.1]) by ext.lri.fr (Postfix) with ESMTP id 25F5DA42EB for ; Mon, 9 Feb 2009 13:51:55 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at lri.fr Received: from ext.lri.fr ([127.0.0.1]) by localhost (ext.lri.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 1f1jRbdouSuF for ; Mon, 9 Feb 2009 13:51:55 +0100 (CET) Received: from smtp.lri.fr (vhost3-23 [129.175.3.23]) by ext.lri.fr (Postfix) with ESMTP id 0E2B9A42BC for ; Mon, 9 Feb 2009 13:51:55 +0100 (CET) Received: from [129.175.4.107] (lri4-107 [129.175.4.107]) by smtp.lri.fr (Postfix) with ESMTP id 158D9E056E for ; Mon, 9 Feb 2009 13:51:55 +0100 (CET) Message-ID: <499026F9.3030708@lri.fr> Date: Mon, 09 Feb 2009 13:52:09 +0100 From: Romain Bardou User-Agent: Thunderbird 2.0.0.19 (X11/20090105) MIME-Version: 1.0 Cc: OCaml List Subject: Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3) References: <1233936696.6216.65.camel@Blefuscu> <200902071458.45000.jon@ffconsultancy.com> <498FF839.6090901@lri.fr> <499018C2.9080007@lri.fr> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Spam: no; 0.00; lri:01 ocaml:01 wiki:01 ocaml:01 wiki:01 mailling:98 highlighted:98 caml-list:01 argument:02 simplest:02 api:02 authors:03 authors:03 well-written:03 well-written:03 >> Is it just a matter of copy/pasting the contents of the wiki into the >> OCaml manual? > > Are you serious ? You don't have to be so mean :( > Yes, the way the plugin api works is still lagely undocumented (a random > example is it possible to use Plugin.flag inside a rule and what would > the effects be ? another is why is the tags argument of Plugin.rule > deprectated and thus how can I make a rule apply only if a file has a > given tag or maybe I shouldn't do that, etc.). Unfortunately, while authors might be the best persons to answer these questions, they are also the ones who do not have any question ;) Finding the right questions is not easy and a Wiki is a nice way to find out. > There are a lot of things the authors of ocambuild know that are not in > the wiki and that I don't want to discover by trial/error/understand the > ocamlbuild source/consult mailling list/try to look at the wiki and I'd > be very grateful to them if they'd share this knowledge in a > well-written manual. > >> As far as I can tell it does answer a lot of the questions you >> highlighted. > > Many people don't understand that very often the barrier to adoption is > just a single, extensive source of documentation called a manual. Let me > repeat that again, a wiki (or its content) is not a substitute for a > manual. The whole carefully edited "big picture" documentation is > missing and you won't get that by copy and pasting random samples from > the wiki. We need this well-written thing called a manual that any > respectful tool should provide, they had a good start here [1] but it is > not sufficient as it covers only the simplest cases. While I agree that the documentation should answer most questions, I fail to see how "try to look at the wiki" is different from "try to look at the manual". The only problem I have with the wiki is that it is not in the same place as the OCaml manual. Do we have to rename "wiki" into "manual in which you can write your own notes" ? :) -- Romain Bardou