Subject: Re: What information belongs into man pages?
To: None <tech-userlevel@NetBSD.org>
From: Alan Barrett <email@example.com>
Date: 10/19/2006 08:46:39
On Wed, 18 Oct 2006, Roland Illig wrote:
> the recent thread on the isspace(3) function motivated me to write an
> explanation about the topic, and I would like to include it in the
> ctype.3 man page, so that it looks like the appended one.
It looks good, but I haven't studied it closely.
> Now the questions are:
> - What target audience do we have for the man pages?
> - C language lawyers (in that case it wouldn't be necessary)
> - Casual C programmers (who may find the information useful)
> - Beginners (to whom the information is essential)
I would say that the target audience is all of the above. We should
provide accurate information for language lawyers, and helpful
information for beginners.
> - Do we want to provide such programmer-friendly documentation that
> tries to prevent bugs, increasing the code quality?
> - Or are the man pages just references, and we don't care much about
> their quality?
Are you suggesting that (being a reference) implies (quality does not
matter)? I don't think the one implies the other at all.
I think that the man pages are references, and that we should care
deeply about their quality. I think that it's useful to provide some
tutorial material, much as you have done in this case, but that we
should stop short of making the man pages a "how to learn to be a
programmer" guide book.
--apb (Alan Barrett)