Subject: Linux Documentation Project
From: [email-masked] (Matt Welsh)
Date: Mon, 15 Feb 1993 01:28:44 GMT
Newsgroups: comp.os.linux,comp.os.linux.announce

A couple of weeks ago, Lars decided to hand over coordination of the
"Linux Documentation Project" (actually the DOC channel of the mailing list).
And I, being the brainless gnat that I am, volunteered to take it over
for him. I suppose I have time for this, I guess we'll see. :)

Lars has asked me to make an announcement to this effect, and to let you all
know of the status of the Doc Project. So, as it stands now, I'm the
coordinator of the Doc Project, so if you have questions, comments, or want
to volunteer, you can mail me. 

For the most part we're just waiting for the writers to finish their 
respective docs, so that all of us on the Doc Project can proofread and
edit them into submission.

As always, to join the DOC channel of the mailing list, just send mail to
	[email-masked]
with the line
	X-Mn-Admin: join DOC
at the top of the body (not the subject).

Printed below is an edited version of a "Doc project update" that I sent
out a little while ago. If you already know about the Doc Project then
you can hit "n" to skip this bit. :)

Cheers,
mdw

This note is going out to keep the masses informed of the current status
of the Linux Doc project, as we've all been pretty quiet recently.

Essentially, we're all off hiding in our respective corners, trying to
churn something out. I imagine that it may be a while before we have anything
complete and proofread enough to 'distribute'. However, here's the status
of the 'Doc Project' as it now stands:

The main project is the 4 manuals. These will be the Installation/Setup/Getting
Started manual (coordinated by myself), the User's Manual (coordinated by
Larry Greenfield), the System Administrator's Guide (coordinated by Lars
Wirzenius), and the Kernel Hacker's Guide (Michael K. Johnson?). What we're
aiming for is to write and maintain the canonical set of Linux documents--
books that are well-written, well-formatted, and well-edited, and complete.
Since the Linux world is getting ready to expand far beyond the horizon of
the net (where anyone can get help via news or e-mail) with the advent of
CD-ROM releases and so on, I think we need good, complete manuals, and soon.

We've all pretty much agreed to format the manuals in LaTeX, using the
standards sent out by Michael K. Johnson. He's produced a LaTeX style format
that should be used for the manuals, and written a conventions page that
details how to use the macros. It's very simple, and they should be adhered
to if possible. LaTeX/TeX under Linux supports them quite well, if you don't
have access to LaTeX elsewhere. :) 

Filters are being written to convert the LaTeX source to texinfo format. 
Don't worry: These manuals will be available in one form or another in 
online format.

Man pages and other documentation are also being discussed on this channel.
We'll talk more about that later, I suppose...

I don't know about the status of all of these manuals. I'm waiting for 
progress reports to filter in from the other writers, but from what I can tell 
we're all happily writing along. The coordinator of the Doc Project as a whole
is myself ([email-masked]), and I'm going to (attempt to) make sure that
all of the manuals fit together, don't have conflicting information, don't
have teriblle mispelings [sic], and so on.

Once the individual writers have their alpha versions ready, anyone
on the DOC project will be able to edit/proof them so we can have them
ready for general distribution as soon as possible. The DOC channel will
be used for this purpose as well.

As far as the Linux Installation/Setup/Getting Started manual is concerned,
it will be the be-all-end-all of Linux installation and getting started 
documents, as much as such a thing can exist in the Linux world. It won'
t replace documents like the FAQ (which are composed of many somewhat 
unrelated important pieces of information). The intended audience is both for 
the complete UNIX newbie, as well as for seasoned UNIX hacks who have just 
never installed Linux before. It will be VERY complete, and I plan to maintain 
it, and keep up with changes in the Linux world. A very general outline will 
look something like:
  -- Introduction (What is UNIX? What is Linux?)
  -- How do I get Linux (intro to the various releases, how to get them
     from various sources)?
  -- How do I install Linux (parallel of above; cover installation for
     each release)?
  -- Setting up the system; beginner's tutorial in UNIX
  -- Beginner's Tutorial in System Administration (just the basics, may
     serve as an intro to the System Admin guide... written by Lars).
  -- How to upgrade/install new software, libs, GCC, kernel, and so on.
     (*** This is technically 'Installation', but I imagine we should put this
     in the system admin guide, no?).
  -- Common problems, troubleshooting, and so on.
  -- Appendices: other UNIX books to check out, introduction to FTP (for those
     who will get Linux over the net), other rudimentary info.

A lot of this will be obvious to people who have worked with UNIX before, and
more 'advanced' topics will be seperated from the beginner's stuff. I don't
want UNIX gurus skipping through the entire manual, however. I may provide,
as an appendix, some kind of summary for those familiar with UNIX and the net
(for those who can read a 3-5 page doc on where to get Linux and how to 
install it). This may be implemented as a seperate short document, 
putting most of the info from section III of the FAQ into a more readable
format. You may have noticed that my instructions on how to install Linux
in the FAQ are rather sketchy: "To get Linux, FTP the images, rawrite them
to disks, and boot the boot disk. Voila!" I need to flesh this out a little
in another kind of document... things to be covered include making filesystems
and partitions, making a kernel floppy, etc... anything that a UNIX hack can
already do, but needs specific instructions on how to do under Linux. 

The intended audience for the System Admin guide and User's Guide should
probably be more towards those who have done at least a little work with
UNIX before. I don't know if the writers of those manuals want to cover 
all of the basics or if they only want to talk about the Linux-specifics. 
They could probably compromise: write a good introduction, give some basic
information, then point to other well-written UNIX books for further starter's
hints, allowing the rest of the manual to be geared towards a detailed guide.

I apologize that this is so long. In the time it took to write this, I could
have finished a chapter or two. Please make comments or suggestions, if you
made it all the way through. Thanks!
-- 
Matt Welsh, [email-masked] 
  "What are you doing, Dave?"