Date: Fri, 20 May 2005 11:33:39 -0700 From: Vizion <vizion@vizion.occoxmail.com> To: freebsd-questions@freebsd.org Subject: Re: Pine (Tony Shadwick) & giving in to temptation(s) Message-ID: <200505201133.40462.vizion@vizion.occoxmail.com> In-Reply-To: <200505201109.05441.dfarmour@myrealbox.com> References: <20050520165023.EB3B316A4D4@hub.freebsd.org> <200505201109.05441.dfarmour@myrealbox.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200505201133.40462.vizion>