Re: Answering frequently asked questions

[Tony Earnshaw <tonye@billy.demon.nl>]

lør, 20.12.2003 kl. 16.18 skrev Pierangelo Masarati:

> The first type is always ahead of code (unless expired,
> deprecated or so), the last type always lags behind.
> 
> That's why Howard insists in telling you to read the code.
> In a perfect world, each release, even minor, would be based
> on carefully examining well thought documents of the first
> type, and come along with fully up-to-date documentation
> of the second type.
> 
> Since this doesn't even happen for commercial software,
> despite the price you may get charged for, don't expect
> it from open-source projects.

I know it's not fair picking and choosing a single point, possibly out
of context, from a comprehensive set, but the above argument fails on
its own inconsequentiality. Like "it's rubbish". Your answer is simply
an excuse for having done something badly.

Examples of Open Source projects that provide excellent and
understandable documentation (and for many, the mailing list users are
told to read the docs before posting questions) are:

- Postfix, where the developers produce patches for the docs along with
code patches;

- Exim, where the docs (spec.txt, NewStuff) are completely reviewed with
each minor change;

- mod_apache/ssl, which surely has the best documentation available
anywhere;

- Apache itself;

- kernel.org kernel docs;

- The newer ISC BIND (9.2.3 is the latest, and the one I use from
preference),

etc. etc.

Arguably, the hardest part of Openldap to understand and implement for
mortals (apart from difficulties with compiles on non-standard OSs) are
the ACLs. Good and understandable docs *are* needed badly. If no-one but
the developers are capable of writing these in clear and good English,
then the developers should write them *and* have the result vetted by a
native English speaker - preferably a "tame" documentation expert.

No way can you shove the blame for not understanding the implementation
of the tools you supply in Openldap onto the end user by telling
[him|her] to read the code (why have any docs, man pages in the first
place? "Just read the code, man!"). To do so smacks of the sort of very
bad excuse that one might expect from a juvenile.

--Tonni

-- 
mail: billy - at - billy.demon.nl
http://billy.demon.nl