[Date Prev][Date Next] [Chronological] [Thread] [Top]

Re: documentation

I wrote:
>Howard Chu writes:
>> I strongly dislike the tendency to make the Admin Guide repeat
>> everything that's already in the manpages.
> I agree.

On second thought, that's a bit strong.  Some of the duplication is
useful.  It's good to have the admin guide more or less self-contained,
so one can get through read it without referring manpages all the time.
And after all the admin guide is edited to be readable and show the
"you likely need to know this" parts, while manpages are not selective.

The main problem is that the guide doesn't say what is copied.  It would
help a lot just to prefix manpage extracts with "From the slapd-foo(5)
manual page:", ensure the copy is verbatim, and use another font for it.

I do think too much is copied, but that's secondary.

BTW, another advantage with duplication: The admin guide can be more
convenient to _print_ than a bunch of manpages.  That's an issue which
might be solved in a completely different way though.