Pine (Tony Shadwick) & giving in to temptation(s)

[Vizion]

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 at freebsd.org mailing list
& http://lists.freebsd.org/mailman/listinfo/freebsd-questions
& To unsubscribe, send any mail to
 "freebsd-questions-unsubscribe at 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.