Re: ocamlbuild documentation (was Re: [Caml-list] Re: [ANN] OCaml Batteries Included, alpha 3)

[Kuba Ober <ober.14@osu.edu>]

> 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