From: knapka@athena.cs.uga.edu (Joseph Knapka)
Newsgroups: comp.os.linux
Subject: User's Guide project
Date: 11 Apr 92 19:06:45 GMT
Organization: University of Georgia, Athens

Hi, folks.

There's an embryonic project underway to collect/write a reasonably
coherent User's Guide to Linux. I include here an excerpt of recent
discussion from the man-page mailing list, and invite comments on the
plan outlined. We're especially looking for comments / criticism /
volunteerism on the following points:

1) Do you think there is a need for such a document?

2) Does the organization outlined seem reasonable? Should it be
expanded/changed? I know it's a bit vague at the moment, but it can't
be made less so without feedback...

3) Would you be willing to contribute a chapter on a particular
subject or software package? This is important --- the level of
technical expertise among those of us on the manpage list is, in many
cases, not sufficient to turn out the sort of documentation we're
lookin' to compile. We can, however, make sure that documentation is
edited into a readable-for-beginners form without distorting the
content. So we need help from the real experts.

Post, or send email to jknapka@aisun2.ai.uga.edu. 

Thanks,  

Joseph 

----------------------- Begin included text ------------------------
From: johnsonm@stolaf.edu (michaelkjohnson)

>
>From: jknapka@aisun1.ai.uga.edu (Joseph Knapka [MSAI])
>
>   > What I envision is a single coherent document that consists of
>   > chapters devoted to each major package (TeX, groff, gcc [whatever's
>   > currently most stable], emacs... and maybe some not-so-major ones) and
>
>My list: (partial, my mind is not good enough to do a complete one ;-)
>1) TeX -- We should encourage good typesetting
>2) Groff -- ditto.
>  --notice that there is a lot of basic stuff available already on
>    how to use these programs, like "A gentle intro to TeX."  But
>    we could certainly use good installation instructions that
>    covered what all the files are for, which are optional, etc.
>3) emacs
>4) gcc
>  --at least 1-4 need detailed instructions on what different files
>    mean.  I think that for typesetting packages, for instance, you
>    would want to spend time on font files, how to generate and
>    manipulate them, etc.
>  --gcc itself would need not only information on how to get shared
>    libs to work (for example), but also _basic_ information on how
>    they are implemented.  I think that a little enlightenment in
>    these areas never hurts, as long as it is not done in a painfully
>    obtuse way.
>5) ka9q
>6) kermit, pcomm, xcomm/xc, other comm packages
>7) uucp (now out at tsx-11! --thanks, Ed)
>8) gnu info
>9) X
>10)mail/smail/elm/sendmail/etc.
>
>   > answers the following questions:
>
>   > 1) How do I install this package? Best-case scenario. Including
>   > Where do I get it?
>
>   > 2) What are the major stumbling blocks encountered by others during
>   > installation, and how do I fix them?
>
>   > 3) Why do I need this package? Give me two or three good reasons why I
>   > should devote valuable disk space to it.
>
>   > And whatever else people think is appropriate/necessary. An advantage
>   > of this format is that the individual chapters on each package can be
>   > written by anyone, and the coordinator can edit them into a coherent
>   > whole. Moreover, the individual chapters could be available separately
>   > with the packages. Ultimately, the Beginner's Guide installation info
>   > could be included, to create a genuine user's manual for Linux.
>
>   > We can also include info on ports that have been done but which aren't
>   > available at the Linux-aware ftp sites (i.e. GNU software that needs
>   > only trivial Makefile changes to compile).
>
>Yes.  Especially info on common changes that have to be made -- Things
>like take the g off gnu products, in general, because they are the
>only ones we are using generally.  What things commonly have to be
>defined, (hopefully -DPOSIX :-) what differences people are likely to
>find in things like devices, (like no raw versions of devices) etc.
>
>   > Thoughts?
>
>   > Joseph
>
>As far as this goes, I think that it is good.  I would also like to
>see "How to administer your linux system" and "Linux security
>features: what do you need?" and other such topics covered.  I don't
>think that they belong in the same volume as one devoted to getting
>software to work, though perhaps in a companion volume...
>
>Perhaps some documentation on using Linux for a BBS would be worthwhile.
>
>We now have e-net support through ka9q.  Once we add full network
>support, I imagine Brenden Kehoe (I don't think I spelled that right)
>wouldn't mind if we included "Zen and the Art of the Internet," a
>guide to the internet that he wrote which is available in texinfo
>format.
>
>Which brings up the point:
>A lot of the stuff we are looking at may have been written already.
>Keep your eyes open, use archie to find things, whatever -- We have
>not invented a lot of new needs -- Just created a way to express them.
>
>BTW:  I am going to be writing a document on the man page project for
>the docs/man directory at tsx-11.  If anyone has any ideas that they
>think should be in that document, please send them to me so that I can
>include them.
>
>michaelkjohnson
>johnsonm@stolaf.edu
>linux-man-request@stolaf.edu

---------------------- End of included text ------------------------
Newsgroups: comp.os.linux