[nycbug-talk] From Dru's blog

[michael]

On Fri, 09 Nov 2007 10:27:07 -0500
"Dan Langille" <dan at langille.org> wrote:

> On 9 Nov 2007 at 9:06, George Rosamond wrote:
> 
> > While I see their point about the goal of how-to's/tutorials, I
> > think they're a bit dismissive of the man pages.

I will have to agree that it was a little dismissive of man pages.

	"Do not write a man page. Man pages are examples of... theory
	through theory. Have you ever tried to use a completely new
	application straight by looking at the man page? How long did
	it take you to reach the information on how to use the tool in
	practice, going just through various option descriptions? Well,
	this is not what our readers want."

It was implied that the man page is not a good source to learn an
application.  Not only does that sound dismissive; it sounds plain
wrong. I will have to take it from context that BSD users were not the
target "readers" of the above quote. At least not for anything in base. 

> In general:
>  - man pages contain the facts, and not much else.
>  - man pages lack practical examples to get a novice started
> 
> They aren't dismissing man pages.  They are saying we need more than 
> man pages.  So don't give us a man page.
> 
> -- 
> Dan Langille - http://www.langille.org/
> Available for hire: http://www.freebsddiary.org/dan_langille.php


Please do not take this as aggressive or confrontational, but I take
exception to the above statements. 

The 'manual' should be the source for usage; and should be complete.
If the man page is deficient, shouldn't it be corrected or appended?  I
can understand if this was linux or solaris (both have sub-par man
pages, imo), but this is BSD. Man pages are excellent.  They contain
facts and so much more!  I am of the opinion that one should not need
*more* than man pages.

Man pages *do* have EXAMPLES sections.. e.g.

$ man ls

[snip]

EXAMPLES
     List the contents of the current working directory in long format:

           $ ls -l

     In addition to listing the contents of the current working
     directory in long format, show inode numbers, file flags (see
     chflags(1)), and suffix each filename with a symbol representing
     its file type:

           $ ls -lioF

     List the files in /var/log, sorting the output such that the
     mostly re- cently modified entries are printed first:

           $ ls -lt /var/log


Granted, the 'call for articles' is probably not for system programs
like ls, but for 3rd party programs.. which are not part of "latest
distro releases" [sic].  

So, if the context was 'articles about programs outside of base'; then
OK.  Some 3rd party software is poorly documented, and articles can be
helpful.  But then.. that is not BSD specific.  Those articles can be
published in LJ.

Please do not get me wrong.  I like articles.  I like to read them  and
I like to write them, sometimes.  I even like the idea of a mag. Paper
is easier to read on the train or in the head than man pages [grin].


-- 

michael