From owner-freebsd-hackers@FreeBSD.ORG Thu Jul 19 08:33:22 2012 Return-Path: Delivered-To: freebsd-hackers@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id B63A91065674 for ; Thu, 19 Jul 2012 08:33:22 +0000 (UTC) (envelope-from wojtek@wojtek.tensor.gdynia.pl) Received: from wojtek.tensor.gdynia.pl (wojtek.tensor.gdynia.pl [89.206.35.99]) by mx1.freebsd.org (Postfix) with ESMTP id 12CD28FC0C for ; Thu, 19 Jul 2012 08:33:21 +0000 (UTC) Received: from wojtek.tensor.gdynia.pl (localhost [127.0.0.1]) by wojtek.tensor.gdynia.pl (8.14.5/8.14.5) with ESMTP id q6J8XK2j007550; Thu, 19 Jul 2012 10:33:20 +0200 (CEST) (envelope-from wojtek@wojtek.tensor.gdynia.pl) Received: from localhost (wojtek@localhost) by wojtek.tensor.gdynia.pl (8.14.5/8.14.5/Submit) with ESMTP id q6J8XKnp007547; Thu, 19 Jul 2012 10:33:20 +0200 (CEST) (envelope-from wojtek@wojtek.tensor.gdynia.pl) Date: Thu, 19 Jul 2012 10:33:20 +0200 (CEST) From: Wojciech Puchar To: Dave Hayes In-Reply-To: <5007129E.6020701@jetcafe.org> Message-ID: References: <20120717183221.298430@gmx.com> <20120717153505.42633535@bhuda.mired.org> <5005D181.8080709@jetcafe.org> <5007129E.6020701@jetcafe.org> User-Agent: Alpine 2.00 (BSF 1167 2008-08-23) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Greylist: Sender passed SPF test, not delayed by milter-greylist-4.2.7 (wojtek.tensor.gdynia.pl [127.0.0.1]); Thu, 19 Jul 2012 10:33:20 +0200 (CEST) Cc: freebsd-hackers@freebsd.org 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: Thu, 19 Jul 2012 08:33:22 -0000 > 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. manual pages are intended to PROPERLY describe how program/function etc. operates. > Of course, I doubt anyone can make a case for the 'one true right way' to > learn FreeBSD. True. > 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 why? > The notion of a 'new user' is unfortunately too wide of a category to target > documentation to. The problem of today is "persistent new user". "New user since first time touched computer". > 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. Secretary should not be FreeBSD admin, while of course can be FreeBSD user. Unix makes clear distinction between user and admin. Modern computing style blurs it. > 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? No idea. What i HATE in very modern software is wiki-style "documentation". >> 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. snapshots do crash on big filesystems. And after background fsck often you will find more errors by foreground fsck. Anyway it is not a problem really. Just don't make bulky virtual volumes of 100 disks, as it is not just slow to fsck but dangerous. if your server works for people that cannot stand half an hour of downtime then change to 0 all /etc/fstab positions except of most important, then after a crash do fsck after worktime. with softupdates it is generally safe to run filesystem without fsck for some time. > >> 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? :) First "good" must be needed. Now "good" is defined by democratic means buy herd of "persistent newbies". Doing nothing is actually better than create new "goods" like that.