From owner-freebsd-questions@FreeBSD.ORG Fri May 20 20:02:39 2005 Return-Path: Delivered-To: freebsd-questions@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id E9CDD16A4CE for ; Fri, 20 May 2005 20:02:38 +0000 (GMT) Received: from lakecmmtao05.coxmail.com (lakecmmtao05.coxmail.com [68.99.120.79]) by mx1.FreeBSD.org (Postfix) with ESMTP id 35FE243DB7 for ; Fri, 20 May 2005 20:02:38 +0000 (GMT) (envelope-from vizion@vizion.occoxmail.com) Received: from dns1.vizion2000.net ([64.58.171.82]) by lakecmmtao05.coxmail.comESMTP <20050520200237.SIBD7226.lakecmmtao05.coxmail.com@dns1.vizion2000.net> for ; Fri, 20 May 2005 16:02:37 -0400 From: Vizion To: freebsd-questions@freebsd.org Date: Fri, 20 May 2005 11:33:39 -0700 User-Agent: KMail/1.8 References: <20050520165023.EB3B316A4D4@hub.freebsd.org> <200505201109.05441.dfarmour@myrealbox.com> In-Reply-To: <200505201109.05441.dfarmour@myrealbox.com> MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200505201133.40462.vizion@vizion.occoxmail.com> Subject: Re: Pine (Tony Shadwick) & giving in to temptation(s) X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 20 May 2005 20:02:39 -0000 On Friday 20 May 2005 11:09, the author David Armour contributed to the dialogue on Re: Pine (Tony Shadwick) & giving in to temptation(s): & hello, & & > I'm getting more and more tempted to start up a wiki for newbies on good & > package management practices and port management. & & get on with that, wouldya? & & > The handbook seems to deal well with these things once you know & & lots of ways to get yourself into lots of deep water, yes. and a large & disparity between beginners and experts. I believe the challenge faced by writers of additional manuals for unix systems is how to bridge the very wide gap between clean slate approach for newbies and the assumed minimum knowledge level standards which prevail in existing documentation. My suggestion would be to build upon what we already have and: 1. create a project which extends existing man pages by: (a) Using an XML implementation of man pages to facilitate searches for meaning rather than just words. (b) Reviewing each man page and producing a clean slate version for each page. (c) Create links in the man pages to provide a clean slate presentation of concepts which are relevant to the contents of the page. Each such link (and sub links) would need to be organized so the reader could return to the start or any intermediate page s/he has travelled at any time . This could perhaps be achieved by a backward tracking module written in java. (d) Write a clean slate introduction manual which puts the whole within a conceptual framework and links to expanded man page system. (e) provide a framework with a user notes sytem such as is already provided by some X-windows manual implementations. 2. If you want to use a clean slate approach its definition would pose a challenge. I would offer a draft guideline in the following terms: "The objective is to enable any user to enter any page with zero knowledge and as a result of studying the page, and any links s/he has the opportunity of both (i) understanding the material and (ii) placing the material in context (ii) putting the knowledge gained into practice" 3. The latter requirement means that any smart manual would be rich in application examples and illustrate (i) circumstances in which the commmand is applicable (ii) identify similar circumstances for which the command is not appropriate (iii) identify appropriate alternative commands for those circumstances. & & > Granted, an argument could be made that you should read the handbook cover & > to cover before you begin. ;) Who actually DOES that though? & & there are large portions of the handbook that demonstrate vividly just how & profound my lack of understanding remains, despite repeated attempts. i'd & definitely welcome an intermediate level documentation. and a convenient & means to confirm a) accuracy and b) timeliness, both of which seem & non-trivial to me, would also help. & & regards. & _______________________________________________ & freebsd-questions@freebsd.org mailing list & http://lists.freebsd.org/mailman/listinfo/freebsd-questions & To unsubscribe, send any mail to "freebsd-questions-unsubscribe@freebsd.org" & -- 40 yrs navigating and computing in blue waters. English Owner & Captain of British Registered 60' bluewater Ketch S/V Taurus. Currently in San Diego, CA. Sailing May bound for Europe via Panama Canal.