Newsgroups: comp.os.linux,comp.os.linux.announce From: mdw@db.TC.Cornell.EDU (Matt Welsh) Subject: Linux Documentation Project Message-ID: <1993Feb15.012844.19514@tc.cornell.edu> Date: Mon, 15 Feb 1993 01:28:44 GMT Approved: linux-announce@tc.cornell.edu (Matt Welsh) 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 linux-activists-request@niksula.hut.fi 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 (mdw@tc.cornell.edu), 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, mdw@tc.cornell.edu "What are you doing, Dave?"