Howard Chu writes:
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.
This sounds good - with one exception: If the documented feature is not too trivial to use I like manpages with an example or two. A glance at them early can provide a mental hook into which to plug the rest of the manpage. They can clarify things if either author or reader didn't get straight, though that may also mean the manpage should be fixed. And I think they are a valid place to sneak in some "admin guide"-like info. Examples of what the documented feature can be used for, and hints about other chatty stuff one doesn't want to waste the reader's time with in the "normative" manpage text.
OTOH I'm fine with calling it a manpage defect if removing an EXAMPLE(S) section would remove information about the documented feature. With a few exceptions, like if the text elsewhere refers to the examples because it'd be too complicated to explain otherwise.
I strongly dislike the tendency to make the Admin Guide repeat everything that's already in the manpages.
I agree.