From owner-freebsd-hackers@FreeBSD.ORG Wed Jul 18 19:46:39 2012 Return-Path: Delivered-To: freebsd-hackers@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id 63E191065674 for ; Wed, 18 Jul 2012 19:46:39 +0000 (UTC) (envelope-from dave@jetcafe.org) Received: from nahkohe.jetcafe.org (nahkohe.jetcafe.org [205.147.26.32]) by mx1.freebsd.org (Postfix) with ESMTP id 23F8F8FC16 for ; Wed, 18 Jul 2012 19:46:39 +0000 (UTC) X-Envelope-To: Received: from [205.147.26.5] (hokkshideh4.jetcafe.org [205.147.26.5]) by nahkohe.jetcafe.org (8.14.2/8.14.2) with ESMTP id q6IJkcIt014834 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Wed, 18 Jul 2012 12:46:38 -0700 (PDT) Message-ID: <5007129E.6020701@jetcafe.org> Date: Wed, 18 Jul 2012 12:46:38 -0700 From: Dave Hayes User-Agent: Mozilla/5.0 (X11; FreeBSD amd64; rv:13.0) Gecko/20120612 Thunderbird/13.0 MIME-Version: 1.0 To: freebsd-hackers@freebsd.org References: <20120717183221.298430@gmx.com> <20120717153505.42633535@bhuda.mired.org> <5005D181.8080709@jetcafe.org> In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: Resistance to documentation? (was Re: Pull in upstream before 9.1 code freeze?) X-BeenThere: freebsd-hackers@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Technical Discussions relating to FreeBSD List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 18 Jul 2012 19:46:39 -0000 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