Skip site navigation (1)Skip section navigation (2)
Date:      Wed, 18 Jul 2012 12:46:38 -0700
From:      Dave Hayes <dave@jetcafe.org>
To:        freebsd-hackers@freebsd.org
Subject:   Re: Resistance to documentation? (was Re: Pull in upstream before 9.1 code freeze?)
Message-ID:  <5007129E.6020701@jetcafe.org>
In-Reply-To: <alpine.BSF.2.00.1207181024250.4615@wojtek.tensor.gdynia.pl>
References:  <20120717183221.298430@gmx.com> <20120717153505.42633535@bhuda.mired.org> <5005D181.8080709@jetcafe.org> <alpine.BSF.2.00.1207181024250.4615@wojtek.tensor.gdynia.pl>

next in thread | previous in thread | raw e-mail | index | archive | help
On 07/18/12 01:36, Wojciech Puchar wrote:
> not really. the idea was to integrate it with shell and turn on it by
> default, prefering newbies over norml users, and making another change
> that would actually prevent getting knowledge to newbie.

I don't agree with modifying the shell either, and I really doubt that 
is going to happen here.

>> I've been using FreeBSD since the 90s. My perception (over many years
>> of observation) is that the FreeBSD people most able to document what
>> exists and how to use it seem to also have the greatest resistance to
>> writing any documentation.
>
> what do you mean? FreeBSD manual pages is what i consider great part.
>
> i mean manual pages. handbook is not always up to date but still fine
> for a NEW USER to learn FreeBSD.
>
> And that's the right way.

While I have learned much from man pages, as I remember hearing it 
explained to me...man pages are -reference- material. They are not 
intended to be the 'right way' to learn something, but instead as a 
quick reference guide.

Of course, I doubt anyone can make a case for the 'one true right way' 
to learn FreeBSD. I would never teach someone to read the man pages as a 
way to familiarize themselves with...say...geom(8). (In fact, I'd love 
to find some better introductory/overview documentation for geom,
but I digress.)

The notion of a 'new user' is unfortunately too wide of a category to 
target documentation to. A secretary who's never seen anything but 
windows, a 5 year old child, and a fresh PhD in computer science might 
all fit this category. Each of these people requires different levels of 
teaching.

Everytime I see these discussions my mind flashes to a web based wiki 
where everyone writes helpful information (like the Emacs Wiki) on 
various topics and it's fairly well indexed so you can see related 
ideas. Does something like this exist for FreeBSD?

> 4) Adding features that are not really finished and in working state.
> gjournal is an example, background fsck is another (everyone actually
> ends in background_fsck=NO)

Well you have me there, I thought background fsck worked...I just left 
it on because it's set like that in /etc/defaults/rc.conf.

> Of course in the same time where are hundreds of good things done, and
> we all know it. But if people won't understand a problem NOW and fight
> it, it will become worse.

If everyone is busy fighting evil, who is left to create the good? :)
-- 
Dave Hayes - Consultant - Altadena CA, USA - dave@jetcafe.org
 >>>> *The opinions expressed above are entirely my own* <<<<

A free society is one where it is safe to be unpopular.
                                           -- Adlai Stevenson



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?5007129E.6020701>