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.