Le 9 févr. 09 à 15:04, Romain Bardou a écrit :
However, there ARE some examples in the part which talks about
"flag", where we clearly see an usage (After_rules).
Which doesn't mean it cannot be used differently.
Anyway it seems useless arguing further: we just don't have the same
standards.
The only thing I see is that there are still a lot of mentions to
makefiles on this list and a lot of new projects don't use
ocamlbuild while ocamlbuild is clearly a superior alternative. The
only way I can explain this is by lack of good documentation.
I'd argue that make's documentation is no better. The TeXinfo pages
distributed with GNU make are useful as a reference, but if you don't
use make much it's a big pain. A good manual IMHO should essentially
have two parts: first is a narrative introduction of all features,
with good examples. Second is a reference section where each command/
setting/UI element is documented in detail.
I have to use make and similarly documented tools (say gnuplot) about
40% of any given 12 month period. I waste lots of time looking for
same information over and over... simply because it's *documented* but
in some hard-to-get-to corner of the hypertext tree. Even Octave's
manual, though more conventional in style, is still written in such a
way that there are no pointers to most common features if all you do
is look at the contents table...
OCaml's manual is, unfortunately, in the same class. For someone who
is not a devoted, full-time user, it's virtually useless. Unless you
know the term/keyword you're looking for, there's no way to find it
short of going through the whole thing page-by-page.
Such manuals are designed to adhere to some 'higher deity' "standards"
of organization, which make them useful to robots perhaps, but nut to
humans. There's utter lack of locality of reference. The authors also
somehow abhor saying things out like they are. Instead of "just saying
it", the sprinkle the information all over the place, in places you'd
least expect to find it.
Suppose I haven't used lists in OCaml much and would like to refresh
my memory. There's a sparse "introduction" to them in section 1.2.
List.map is "introduced" in 1.3; List.assoc in 1.6. The syntax of list
constants (ekhm, sorry, they are called list expressions) is basically
assumed. The list type syntax is given in 19.1. The list concatenation
operator is given in Module Pervasives documentation, in the "List
operations" section. Why the plural? -- beats me. And then there's the
List Module which gives the rest of it. There's no single place that
actually gives list syntax and explicitly says: dude, a list is
written as [ foo; bar; baz ]. Section 6.7 gives expression syntax,
which includes list expressions, but the *narrative* of list syntax is
given in -- of all places -- section 6.7.2 "operations on data
structures", under the heading "Variants". All in all, this is a good
WTF of a manual.
Lisp's hyperspec is, after some getting used to, a better "manual"
than OCaml's "manual" is. Even though a specification is typically
unfit for daily consumption, at least it's reasonably self-consistent,
so once you figure out how it's structured, you'll find things where
you expect to find them. This doesn't address the locality of
reference (there's hardly any) and similar maladies, but at least it
doesn't suffer from lack of self-consistency. It's a bad manual, but
at least everywhere it's bad just the same. OCaml's manual is bad in
many different ways, but not always, and not at the same time. This
actually make's it even worse...
Jon's "OCaml for Scientists" is written more in the way a manual would
be written, but Jon didn't intend to write a manual in the first
place, so I cannot blame him that the book isn't really useable as a
full-blown manual. It does its prescribed job just fine, though.
If there's a good manual I had first-hand experience with, it must be
the one that came with Borland's Turbo Pascal. It was entirely clear
and understandable back when I was in elementary school. This is in
spite of my English being pretty elementary too, back then. Not only
was all the information I ever needed in the manual, but it included
all the nitty-gritty details you needed to interface to Pascal code
from assembly, and the other way around. Down to the layout of
compiler-generated stuff (vtables, packing, etc). It was also included
in the on-line help system, and there the hypertext navigation
actually made it more accessible/navigable. Must be one of the very
few manuals which were originally written on paper, and then meshed
with hypertext while improving usability. I can only give Borland's
doc team from back then highest praise.
Writing good documentation takes skills which don't necessarily mesh
with skills of an accomplished software engineer. It's an added bonus
if a software engineer/scientist is a good documentation writer, but
that's very, very rare. There are many either excellent or pretty
decent open source tools that desperately need a manual written by
someone who knows how to do it. The authors are good at making the
tools, but their technical writing skills leave a lot to be desired.
I'm referencing stuff that I use: OCaml, make, autotools, Octave,
gnuplot, Maxima, ...
Cheers, Kuba
_______________________________________________
Caml-list mailing list. Subscription management:
http://yquem.inria.fr/cgi-bin/mailman/listinfo/caml-list
Archives: http://caml.inria.fr
Beginner's list: http://groups.yahoo.com/group/ocaml_beginners
Bug reports: http://caml.inria.fr/bin/caml-bugs
