[nycbug-talk] From Dru's blog

[Dan Langille]

On 9 Nov 2007 at 11:11, michael wrote:

> 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.

I agree with the quoted text in that learning a new application 
through the app's man page leaves a bit to be desired.

The statement very clearly refers to the application man pages, not 
the users, and not the system (base) man pages.  As such, it applies 
to all users.


> > 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.
> 
> 
> Please do not take this as aggressive or confrontational, but I take
> exception to the above statements. 

No worries.

> 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?

Agreed.  Sadly, in general, many are lacking.


>  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. 

The above is moot given the original quote was about application man 
pages, not system man pages.

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

I agree.  My point was that most [application] man pages lack 
*practical* examples.

> $ 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

Yeah, it's a system man page, relatively ancient, and better written.

> 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.

The content of the articles will be application-general (applicable 
to any OS) to but BSD-specific with respect to things such as 
/usr/local/etc/rc.d/, installation methods, etc.

-- 
Dan Langille - http://www.langille.org/
Available for hire: http://www.freebsddiary.org/dan_langille.php