View Single Post
Old 10th July 2008
scottro's Avatar
scottro scottro is offline
Real Name: Scott Robbins
ISO Quartermaster
 
Join Date: Apr 2008
Location: NYC
Posts: 654
Default

No, the BSD man pages aren't perfect, of course, for as you say, sometimes they too, as well as the handbook at times, are by experts for experts. One difference is that, (probably because of FreeBSD's smaller size) the man page authors and developers are more willing to listen.

(I thought you meant I was right about Corey_James. Speaking of English not being your native language, I think it's better than his, and he's from an English speaking country.)

On the other hand, for example, ifconfig might be hard for the beginner to follow, but at the end, it has the examples section. Robert Watson's page on jails is the example I always give when pointing out how a man page written for the busy professional should be--it doesn't ask you to google all over the place to figure it out, it says do this, then that, then this and explains what's going on.

With third party programs, it's hit and miss. The fluxbox man page is an example, in my mind, of how (and WHO) should write them. The writer is enthusiastic about the program and WANTS you to understand how to use it--it's full of comments like, "With fluxbox, this is easy!" Then shows you how to do it.

The BSD pages might not always be clearer than the Linux ones, but they are far more likely to have an EXAMPLES section, which is the most important. Plus, things ARE documented, even if it's not clear. For example, the RedHat based systems start about 40 programs by default. Many are not documented, or if they are, not to the point where you can really understand if they're necessary or not. Everything in BSD's /etc/rc.d/ and the defaults are documented to a point at least.

Once again, compliments on your English. What country are you from? I had no idea you weren't a native English speaker. (By the way, the "to" of nihonto should probably be tou, it's a long o, and would be written, in Japanese phonetics, as tou.)

Last edited by scottro; 10th July 2008 at 01:01 PM.
Reply With Quote