documentation (was: slapo-chain - can't get it working)

[Hallvard B Furuseth <h.b.furuseth@usit.uio.no>]

Pierangelo Masarati writes:
> Hallvard B Furuseth wrote:
>> Pierangelo Masarati writes:
>>> referral return when writing to a shadow database is handled by the
>>> frontend.  That's why the slapo-chain(5) instance needs to be global.
>>> That's also the main reason global overlays were introduced at all.
>>
>> Please put that in the doc.  (both slapo-chain and replication docs?)
>> Also slapo-chain's "overlay chain" section which says "it is mainly
>> intended for use with local storage backends".  That may be technically
>> correct, but in this context it's misleading.
>
> Slapo-chain is intended to work with local databases.  For the purpose
> of allowing transparently writing to a shadow server, it has to be
> global (for implementation related reasons).

Yes.  But the manpage text by itself is misleading: It says the overlay
works on local storage backends, so one puts it on database bdb or
whatever.  Come to think of it, maybe the same applies if one uses the
'referral' directive.  Haven't tried.

> This IMHO is reflected in the docs: all examples related to
> replication are correct, and blame for the fact that people ignore
> examples in the official documentation cannot be put on the
> developers, nor on those who wrote the documentation.

I'm not interested in blame, but communicating correct information.
The replication section doesn't mention chaining.  Someone who reads
the slapo-chain manpage instead of the admin guide about chaining to
the master won't be told.

Maybe there should be a guide to how to read the docs...
I saw only one example of this one, in the admin guide's chaining
section.  But there are a lot of docs to read, with quite a bit of
duplication by now.  Are people required to read both the admin guide
and the manpages?  Even admin guide sections which mostly seem to repeat
things from manpages, or vice versa?  What if you think you know how
chaining or whatever works because you read its manpage, but the admin
guide mentions a few details the manpages didn't - or vice versa?

-- 
Hallvard