[9fans] Documentation

[9fans] Documentation

[Uriel]

I don't think that the problem is lack of documentation, but that the
existing documentation is badly organized and partially outdated.

If you read:

intro(1) http://plan9.bell-labs.com/magic/man2html?man=intro&sect=1
ftp://ftp.leo.org/pub/historic/comp/os/plan9/old/doc/README.html (Quite
outdated)
http://plan9.bell-labs.com/sys/doc/9.html (Somewhat outdated)
http://plan9.bell-labs.com/wiki/plan9/plan_9_wiki/#USING%20THE%20SYSTEM
http://plan9.bell-labs.com/wiki/plan9/UNIX_to_Plan_9_command_translation
http://plan9.bell-labs.com/wiki/plan9/Tip_o'_the_day
http://plan9.bell-labs.com/wiki/plan9/FAQ/ (Needs updating)
(And there are quite a few more introductory level papers, but they
overlap)

You should have a good starting point; but some of those documents are a
bit outdated, and they are scattered.

I have put some work in cleaning up and organizing the wiki, specially
reducing the amount of cluttered in the main page so it's easier for new
users to find what they are looking for. Help is very appreciated.

Also I have started a "Recommended readings" page that should have
sections for "New Users", "Users" and "Developers"; each populated with
references to relevant papers, man pages, and other documents. So far
it's just a stub, but feel free to fill in stuff:
http://plan9.bell-labs.com/wiki/plan9/Recommended_Readings


Then there is the "Plan 9 Documentation Task Force" which currently is
not very active, but is a good list of documentation tasks which might
be useful:
http://plan9.bell-labs.com/wiki/plan9/Plan_9_Documentation_Task_Force/

Rather than start writing yet more documentation, first lets fix what we
have, which is a lot, and much of it of very good quality.

Thanks

uriel


On Mon, Aug 08, 2005 at 05:42:14PM +0200, Retzki, Sascha [Xplain] wrote:
> > -----Original Message-----
> > From: Christian Walther [mailto:cptsalek@gmail.com]
> > Sent: Monday, August 08, 2005 3:34 PM
> > To: 9fans@cse.psu.edu
> > Subject: Re: [9fans] How to change UserID/Group to edit files in /lib/ndb?
> > 
> > Hi Fans,
> > 
> > thank you for all your answers. I did as Russ suggested and now
> > everything works fine. My next task will be to go through all the
> > documents found in the wiki, but I have to admit that this is a rather
> > painfull task for a newbie. I'm to Unix and as such I'm used to read
> > manpages and other sources of information. But it's sometimes
> > difficult to locate the piece of information needed to perform a
> > certain task, especially if one doesn't know how to perform a certain
> > task.
> > I read some of the papers found on Plan 9s website, but it's just
> > theory as long as one doesn't really work with/on a system.
> > 
> > Because of this, my idea would be to extend the information in the
> > Wiki to some sort of "First steps with Plan 9" document. 
> 
> What about calling it "Plan9 for Unix users"? I am under the impression
> 90% of Plan9 beginners (including myself, btw ;-)) are Unix-users.
> 
> > This is not
> > only about basic information but about "best practices", too. There
> > are several ways of performing a certain task most of the time, but it
> > needs some experience to figure out which way is the best. When this
> > experience is provided by long term Plan 9 users, this can give
> > newbies an impression how to work with it.
> > 
> 
> Amen. The problem is not to find a problem, but to find a solution ;-)
> 
> I know some 9fans from IRC (freenode), among those some persons that
> succeeded in understanding Plan9 (enough to work with it), are unix-users
> and want to write Documentation of this purpose - of course, wanting
> to work, finding time to work and doing the work are three different
> things (again, including myself)