[Date Prev][Date Next]
[Chronological]
[Thread]
[Top]
Re: documentation
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.
--
Hallvard