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

Re: documentation

Hallvard B Furuseth wrote: 
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?

In my opinion, the manpages are meant to be the exhaustive reference on syntax and features. They should not provide (m)any examples. The Admin Guide is *not* meant to be complete, with respect to available options and syntax. It *should* provide examples for common use cases.

In general, when we add new config keywords, I think it is imperative that they are documented in the manpages. It is unimportant to include them in the Admin Guide, but if you're going to show a use case then it's worth mention.

I strongly dislike the tendency to make the Admin Guide repeat everything that's already in the manpages.
--
-- Howard Chu
CTO, Symas Corp. http://www.symas.com
Director, Highland Sun http://highlandsun.com/hyc/
Chief Architect, OpenLDAP http://www.openldap.org/project/