From: dmitry grebeniuk <gdsfh1@gmail.com>
To: "Daniel Bünzli" <caml-list@inria.fr>
Subject: Re: [Caml-list] Re: oasis & macosx
Date: Thu, 21 Apr 2011 20:02:33 +0300 [thread overview]
Message-ID: <BANLkTimEHNAaciLP6Cc3md+TP6HK2TtLVQ@mail.gmail.com> (raw)
In-Reply-To: <BANLkTik+UUT+AhLLJPrC1iubZjZeUtEkPg@mail.gmail.com>
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 <something> that I will
implement soon, but now we will live without it, but it will be
here very soon", or "I've implemented <something>, 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?
next prev parent reply other threads:[~2011-04-21 17:02 UTC|newest]
Thread overview: 22+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-04-20 15:53 [Caml-list] " Daniel Bünzli
2011-04-20 15:55 ` Joel Reymont
2011-04-20 16:12 ` Daniel Bünzli
2011-04-20 16:17 ` Joel Reymont
2011-04-20 16:25 ` Török Edwin
2011-04-20 23:38 ` Edgar Friendly
2011-04-20 16:25 ` Vincent Aravantinos
2011-04-20 16:36 ` Andrei Formiga
2011-04-20 16:58 ` Daniel Bünzli
2011-04-20 17:10 ` Andrei Formiga
2011-04-21 5:58 ` ygrek
2011-04-21 6:00 ` ygrek
2011-04-21 8:55 ` [Caml-list] " Sylvain Le Gall
2011-04-21 16:42 ` Daniel Bünzli
2011-04-21 17:02 ` dmitry grebeniuk [this message]
2011-05-19 9:29 ` Sylvain Le Gall
2011-05-30 11:04 ` Daniel Bünzli
2011-05-30 11:17 ` Gabriel Scherer
[not found] ` <BANLkTim1wCTkwCNZVh_VMYFNa=wkFvCuFA@mail.gmail.com>
2011-05-30 11:47 ` Daniel Bünzli
2011-05-30 13:54 ` Till Varoquaux
2011-05-30 14:06 ` Sylvain Le Gall
2011-05-30 14:56 ` Daniel Bünzli
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=BANLkTimEHNAaciLP6Cc3md+TP6HK2TtLVQ@mail.gmail.com \
--to=gdsfh1@gmail.com \
--cc=caml-list@inria.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).