From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail1-relais-roc.national.inria.fr (mail1-relais-roc.national.inria.fr [192.134.164.82]) by walapai.inria.fr (8.13.6/8.13.6) with ESMTP id p3LH2ehd025651 for ; Thu, 21 Apr 2011 19:02:40 +0200 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: ApsBALFisE3RVdo2mGdsb2JhbACET6B1CBQBAQEBAQgJDQcUJakMijg8giWFDzOIXgEBAwaBI4NQfQSFbog9igo6 X-IronPort-AV: E=Sophos;i="4.64,252,1301868000"; d="scan'208";a="106435347" Received: from mail-yi0-f54.google.com ([209.85.218.54]) by mail1-smtp-roc.national.inria.fr with ESMTP/TLS/RC4-SHA; 21 Apr 2011 19:02:34 +0200 Received: by yie12 with SMTP id 12so808123yie.27 for ; Thu, 21 Apr 2011 10:02:33 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=domainkey-signature:mime-version:in-reply-to:references:date :message-id:subject:from:to:content-type:content-transfer-encoding; bh=ltbcFHCgW06hyzmZjw40g+HJ077gkbLBshDYEJyxPfI=; b=jsPv8yNe+eLWQBO+XqGzkaOOxCS+RXSBGf1VH7Ne9CjgGRrFCOx269/v3OKpPtfnhp J85QCMQBVPVNkK+MY6KahCmt8l/MUsuPnbthokXrlj3KVWOWLmxKrpN/XIReNn7SdLz1 IfpVVJM5Qk6/oTlpKCYbNTid2Stlj1sNOY9XE= DomainKey-Signature: a=rsa-sha1; c=nofws; d=gmail.com; s=gamma; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :content-type:content-transfer-encoding; b=KO9iYTI+QdzZ1/FTAMIkEzEsJLCwZO4h7Oa89VHn0mIrqY1zPmie6CQb5O5czj9ih3 yM2dEBAB3RqNHXFzNw5KzYedJDGZu4uLPr5geoNB0N6tyD7vXtr0zfr8jM1jhf8C8KT5 YYy5AuBXr5QwB5V+0RyfgkX4tsQnunQCpJr3k= MIME-Version: 1.0 Received: by 10.150.159.10 with SMTP id h10mr607570ybe.179.1303405353797; Thu, 21 Apr 2011 10:02:33 -0700 (PDT) Received: by 10.150.185.2 with HTTP; Thu, 21 Apr 2011 10:02:33 -0700 (PDT) In-Reply-To: References: Date: Thu, 21 Apr 2011 20:02:33 +0300 Message-ID: From: dmitry grebeniuk To: =?UTF-8?Q?Daniel_B=C3=BCnzli?= Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-MIME-Autoconverted: from quoted-printable to 8bit by walapai.inria.fr id p3LH2ehd025651 Subject: Re: [Caml-list] Re: oasis & macosx Hello. >> - the documentation can be confusing, because I have written it and I >>  probably know the system too much, ideally someone with no prior >>  knowledge should review it to make it understandable by an oasis >>  beginner (help are welcome on this point) > > I don't think that's a good idea. You built that system, you are the > one who knows it best and if you don't know how to explain it to > others we have a problem. Sometimes the author don't know what exactly users do not understand, since the author himself understands his creature very well. Sometimes the author's plans do not match the code exactly (for example, "there is that I will implement soon, but now we will live without it, but it will be here very soon", or "I've implemented , but it's a temporary solution that will be removed"). If the system is complex enough, I found that using the method "ask the dumb user" is very good for writing basic documentation and FAQs about the system. Also this method helps to list all prerequisites required for understanding the system. btw, I am the dumb user of oasis -- I just know that oasis and oasis-db exist (and I've seen the output of oasis!), and I've written TWO Makefiles today for my new (but very local) ocaml libraries. Sylvain, can I help you if I will be the dumb oasis user?